ontrack-cli 0.1.0__tar.gz

ontrack_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --locked
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Compile package
+        run: uv run python -m compileall ontrack_cli
+
+      - name: Smoke test CLI
+        run: uv run ontrack --help
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*

ontrack_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ontrack-cli/
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import tomllib
+
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]
+          name = project["name"]
+          version = project["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if name != "ontrack-cli":
+              raise SystemExit(f"Refusing to publish unexpected package name: {name}")
+          if tag != expected:
+              raise SystemExit(f"Tag {tag} does not match package version {expected}")
+          print(f"Validated release tag {tag} for {name}")
+          PY
+
+      - name: Build package
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ontrack_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Publish GitHub Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import tomllib
+
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]
+          name = project["name"]
+          version = project["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if name != "ontrack-cli":
+              raise SystemExit(f"Refusing to release unexpected package name: {name}")
+          if tag != expected:
+              raise SystemExit(f"Tag {tag} does not match package version {expected}")
+          print(f"Validated release tag {tag} for {name}")
+          PY
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*.tar.gz
+            dist/*.whl

ontrack_cli-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+.pytest_cache/
+.venv/
+__pycache__/
+*.pyc
+dist/

ontrack_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bunizao
+
+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.

ontrack_cli-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: ontrack-cli
+Version: 0.1.0
+Summary: Terminal-first CLI for the OnTrack/Doubtfire teaching platform
+Project-URL: Homepage, https://github.com/bunizao/ontrack-cli
+Project-URL: Repository, https://github.com/bunizao/ontrack-cli
+Project-URL: Issues, https://github.com/bunizao/ontrack-cli/issues
+Author: bunizao
+License: MIT License
+        
+        Copyright (c) 2026 bunizao
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: browser-cookie3>=0.20
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# ontrack-cli
+
+Terminal-first CLI for OnTrack that reuses your authenticated browser session.
+
+`ontrack-cli` targets Doubtfire / OnTrack deployments and is designed for quick terminal access to your projects, tasks, and teaching roles without building a separate login flow.
+
+## Features
+
+- No manual API token setup in the common case
+- Reads browser auth state from Chrome, Firefox, Brave, or Edge when available
+- Prompts for `base_url` on first run and saves it like `moodle-cli`
+- Lists projects, merged task views, and teaching roles
+- Supports terminal output plus `--json` and `--yaml`
+
+## Requirements
+
+- Python 3.10+
+- `uv` or `pipx`
+- An authenticated OnTrack browser session, or explicit credentials
+
+## Install
+
+```bash
+# Recommended: uv tool
+uv tool install ontrack-cli
+
+# Alternative: pipx
+pipx install ontrack-cli
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/bunizao/ontrack-cli.git
+cd ontrack-cli
+uv sync
+```
+
+## Usage
+
+```bash
+ontrack --help
+ontrack user
+ontrack auth check
+ontrack projects
+ontrack project 12345
+ontrack tasks 12345
+ontrack roles
+```
+
+Structured output:
+
+```bash
+ontrack projects --json
+ontrack project 12345 --yaml
+```
+
+To upgrade after a new release:
+
+```bash
+uv tool upgrade ontrack-cli
+# or
+pipx upgrade ontrack-cli
+```
+
+## Configuration
+
+On first run, if no `base_url` is configured, the CLI prompts for it and writes it to `config.yaml` in the project directory or in `~/.config/ontrack-cli/`:
+
+```yaml
+base_url: https://school.example.edu
+```
+
+Required format:
+
+- Use a full root URL such as `https://school.example.edu`
+- Do not include paths, query strings, or fragments
+- Do not use URLs like `/home`, `/#/projects`, or `/api/auth`
+- The CLI validates the URL against `/api/auth/method` and asks again if it does not look like an OnTrack site
+
+You can also set `ONTRACK_BASE_URL` instead of using the interactive prompt.
+You can copy from [config.example.yaml](config.example.yaml).
+
+Environment overrides:
+
+- `ONTRACK_BASE_URL`
+- `ONTRACK_USERNAME`
+- `ONTRACK_AUTH_TOKEN`
+- `ONTRACK_DOUBTFIRE_USER_JSON`
+
+## Authentication
+
+Default behavior:
+
+1. Resolve `base_url`
+2. Try browser cookies
+3. Exchange OnTrack's browser `refresh_token` for an API auth token when supported
+4. Fall back to explicit environment variables or config values
+
+If browser auto-auth does not work, you can still provide credentials manually:
+
+```bash
+export ONTRACK_BASE_URL='https://school.example.edu'
+export ONTRACK_USERNAME='your_username'
+export ONTRACK_AUTH_TOKEN='your_auth_token'
+```
+
+You can also reuse the front-end cached user object:
+
+1. Open an authenticated OnTrack page
+2. Open DevTools Console
+3. Run:
+
+```js
+copy(localStorage.getItem('doubtfire_user'))
+```
+
+4. Export it:
+
+```bash
+export ONTRACK_DOUBTFIRE_USER_JSON='{"id":123,"username":"your_username","authenticationToken":"..."}'
+```
+
+## Commands
+
+- `ontrack user`: show the resolved signed-in user
+- `ontrack auth check`: validate access and show a quick auth summary
+- `ontrack projects`: list the current user's projects
+- `ontrack project <project_id>`: show a project with merged task definition metadata
+- `ontrack tasks <project_id>`: list task rows for a project
+- `ontrack roles`: list teaching roles for the current user
+
+## Development
+
+```bash
+uv run pytest -q
+uv run python -m compileall ontrack_cli
+uv build
+```
+
+## Notes
+
+- The CLI is built around Doubtfire / OnTrack API behavior
+- Browser-based auto-auth works best when you are already signed in to the target site
+- Some deployments expose `POST /api/auth/access-token`, which allows clean browser-session reuse

ontrack_cli-0.1.0/README.md

@@ -0,0 +1,145 @@
+# ontrack-cli
+
+Terminal-first CLI for OnTrack that reuses your authenticated browser session.
+
+`ontrack-cli` targets Doubtfire / OnTrack deployments and is designed for quick terminal access to your projects, tasks, and teaching roles without building a separate login flow.
+
+## Features
+
+- No manual API token setup in the common case
+- Reads browser auth state from Chrome, Firefox, Brave, or Edge when available
+- Prompts for `base_url` on first run and saves it like `moodle-cli`
+- Lists projects, merged task views, and teaching roles
+- Supports terminal output plus `--json` and `--yaml`
+
+## Requirements
+
+- Python 3.10+
+- `uv` or `pipx`
+- An authenticated OnTrack browser session, or explicit credentials
+
+## Install
+
+```bash
+# Recommended: uv tool
+uv tool install ontrack-cli
+
+# Alternative: pipx
+pipx install ontrack-cli
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/bunizao/ontrack-cli.git
+cd ontrack-cli
+uv sync
+```
+
+## Usage
+
+```bash
+ontrack --help
+ontrack user
+ontrack auth check
+ontrack projects
+ontrack project 12345
+ontrack tasks 12345
+ontrack roles
+```
+
+Structured output:
+
+```bash
+ontrack projects --json
+ontrack project 12345 --yaml
+```
+
+To upgrade after a new release:
+
+```bash
+uv tool upgrade ontrack-cli
+# or
+pipx upgrade ontrack-cli
+```
+
+## Configuration
+
+On first run, if no `base_url` is configured, the CLI prompts for it and writes it to `config.yaml` in the project directory or in `~/.config/ontrack-cli/`:
+
+```yaml
+base_url: https://school.example.edu
+```
+
+Required format:
+
+- Use a full root URL such as `https://school.example.edu`
+- Do not include paths, query strings, or fragments
+- Do not use URLs like `/home`, `/#/projects`, or `/api/auth`
+- The CLI validates the URL against `/api/auth/method` and asks again if it does not look like an OnTrack site
+
+You can also set `ONTRACK_BASE_URL` instead of using the interactive prompt.
+You can copy from [config.example.yaml](config.example.yaml).
+
+Environment overrides:
+
+- `ONTRACK_BASE_URL`
+- `ONTRACK_USERNAME`
+- `ONTRACK_AUTH_TOKEN`
+- `ONTRACK_DOUBTFIRE_USER_JSON`
+
+## Authentication
+
+Default behavior:
+
+1. Resolve `base_url`
+2. Try browser cookies
+3. Exchange OnTrack's browser `refresh_token` for an API auth token when supported
+4. Fall back to explicit environment variables or config values
+
+If browser auto-auth does not work, you can still provide credentials manually:
+
+```bash
+export ONTRACK_BASE_URL='https://school.example.edu'
+export ONTRACK_USERNAME='your_username'
+export ONTRACK_AUTH_TOKEN='your_auth_token'
+```
+
+You can also reuse the front-end cached user object:
+
+1. Open an authenticated OnTrack page
+2. Open DevTools Console
+3. Run:
+
+```js
+copy(localStorage.getItem('doubtfire_user'))
+```
+
+4. Export it:
+
+```bash
+export ONTRACK_DOUBTFIRE_USER_JSON='{"id":123,"username":"your_username","authenticationToken":"..."}'
+```
+
+## Commands
+
+- `ontrack user`: show the resolved signed-in user
+- `ontrack auth check`: validate access and show a quick auth summary
+- `ontrack projects`: list the current user's projects
+- `ontrack project <project_id>`: show a project with merged task definition metadata
+- `ontrack tasks <project_id>`: list task rows for a project
+- `ontrack roles`: list teaching roles for the current user
+
+## Development
+
+```bash
+uv run pytest -q
+uv run python -m compileall ontrack_cli
+uv build
+```
+
+## Notes
+
+- The CLI is built around Doubtfire / OnTrack API behavior
+- Browser-based auto-auth works best when you are already signed in to the target site
+- Some deployments expose `POST /api/auth/access-token`, which allows clean browser-session reuse

ontrack_cli-0.1.0/config.example.yaml

@@ -0,0 +1,10 @@
+base_url: https://school.example.edu
+
+# Option 1: usually leave credentials unset and let the CLI read browser cookies.
+
+# Option 2: paste the exact browser localStorage value from doubtfire_user.
+# doubtfire_user_json: '{"id":123,"username":"your_username","authenticationToken":"..."}'
+
+# Option 3: provide the fields directly.
+# username: your_username
+# auth_token: your_auth_token

ontrack_cli-0.1.0/ontrack_cli/__init__.py

@@ -0,0 +1,3 @@
+"""ontrack-cli package."""
+
+__version__ = "0.1.0"