labtab 0.1.0__tar.gz

labtab-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/

labtab-0.1.0/LICENSE

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

labtab-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: labtab
+Version: 0.1.0
+Summary: Command-line interface for LabTab (Wetware Ltd). Manage your lab from the terminal.
+Author-email: Wetware Ltd <support@wetware.ai>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pydantic[email]>=2.5
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: responses>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# labtab
+
+Command-line interface for [LabTab](https://labtab.app) — the lab management
+platform for Principal Investigators. Manage grants, papers, meetings, tasks,
+projects, and people from your terminal.
+
+Built by [Wetware Ltd](https://wetware.co.uk).
+
+## Install
+
+```bash
+pip install labtab
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+# Pair your terminal with your LabTab account (opens a browser window)
+labtab auth login
+
+# See which labs you belong to
+labtab labs list
+
+# List your grants
+labtab grants list
+
+# Inspect a single grant
+labtab grants show gr_abc123
+
+# Show the next 7 days of meetings
+labtab meetings upcoming --days 7
+
+# Get JSON for scripting
+labtab papers list --json | jq '.[] | .title'
+
+# Export your whole lab as a zip
+labtab export --format zip --lab chen-neuro-lab
+```
+
+## Commands
+
+All commands support `--json` for machine-readable output and `--lab <slug>` to
+override the default lab from your config.
+
+| Command                        | What it does                              |
+| ------------------------------ | ----------------------------------------- |
+| `labtab auth login`            | Pair this terminal with your account      |
+| `labtab auth logout`           | Forget the local API key                  |
+| `labtab auth whoami`           | Show the signed-in user and default lab   |
+| `labtab auth set-base-url`     | Update the stored API base URL            |
+| `labtab labs list`             | Labs you have membership in               |
+| `labtab grants list`           | Grants, filter by `--status`              |
+| `labtab grants show <id>`      | Grant detail card                         |
+| `labtab papers list`           | Papers, filter by `--year`                |
+| `labtab papers show <id>`      | Paper detail with authors, DOI            |
+| `labtab meetings upcoming`     | Meetings in the next `--days` (default 7) |
+| `labtab meetings show <id>`    | Meeting detail card                       |
+| `labtab tasks list`            | Tasks, filter by `--status`               |
+| `labtab tasks show <id>`       | Task detail card                          |
+| `labtab projects list`         | Projects                                  |
+| `labtab projects show <id>`    | Project detail card                       |
+| `labtab people list`           | Lab members                               |
+| `labtab people show <id>`      | Person detail card                        |
+| `labtab export`                | Download a full lab export                |
+
+## Configuration
+
+`labtab` reads and writes its config at `~/.config/labtab/config.toml`.
+Override the path with the `LABTAB_CONFIG_FILE` environment variable.
+
+```toml
+[api]
+base_url = "https://labtab.app/api/v1"
+
+[auth]
+api_key = "lab_api_xxxxxxxx"
+user_email = "pi@example.com"
+default_lab_id = 42
+default_lab_slug = "chen-neuro-lab"
+```
+
+The config file is written with `0600` permissions so other users on the
+machine cannot read your API key.
+
+If you later move the product domain, you can rewrite just the hostname while
+preserving the rest of the API path:
+
+```bash
+labtab auth set-base-url --host labtab.io
+```
+
+## Pydantic models
+
+The package ships two sets of models:
+
+* `labtab.models` (re-exports `labtab.models.api`) — hand-curated, **lenient**
+  models the CLI uses internally. They tolerate extra or renamed backend
+  fields so a CLI install doesn't break when the server ships new columns.
+* `labtab.models.generated` — a **strict**, auto-generated snapshot of the
+  backend's OpenAPI schema. Useful if you want to script against the API
+  directly with precise types.
+
+### Regenerating the strict snapshot
+
+```bash
+# with a running backend at localhost:8000
+datamodel-codegen \
+  --url http://localhost:8000/api/v1/schema/ \
+  --output src/labtab/models/generated.py \
+  --output-model-type pydantic_v2.BaseModel \
+  --input-file-type openapi
+
+# or from a snapshotted schema
+cd backend && python manage.py spectacular --file /tmp/schema.yml
+datamodel-codegen --input /tmp/schema.yml \
+  --output src/labtab/models/generated.py \
+  --output-model-type pydantic_v2.BaseModel \
+  --input-file-type openapi
+```
+
+## License
+
+MIT. See `LICENSE`.

labtab-0.1.0/README.md

@@ -0,0 +1,125 @@
+# labtab
+
+Command-line interface for [LabTab](https://labtab.app) — the lab management
+platform for Principal Investigators. Manage grants, papers, meetings, tasks,
+projects, and people from your terminal.
+
+Built by [Wetware Ltd](https://wetware.co.uk).
+
+## Install
+
+```bash
+pip install labtab
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+# Pair your terminal with your LabTab account (opens a browser window)
+labtab auth login
+
+# See which labs you belong to
+labtab labs list
+
+# List your grants
+labtab grants list
+
+# Inspect a single grant
+labtab grants show gr_abc123
+
+# Show the next 7 days of meetings
+labtab meetings upcoming --days 7
+
+# Get JSON for scripting
+labtab papers list --json | jq '.[] | .title'
+
+# Export your whole lab as a zip
+labtab export --format zip --lab chen-neuro-lab
+```
+
+## Commands
+
+All commands support `--json` for machine-readable output and `--lab <slug>` to
+override the default lab from your config.
+
+| Command                        | What it does                              |
+| ------------------------------ | ----------------------------------------- |
+| `labtab auth login`            | Pair this terminal with your account      |
+| `labtab auth logout`           | Forget the local API key                  |
+| `labtab auth whoami`           | Show the signed-in user and default lab   |
+| `labtab auth set-base-url`     | Update the stored API base URL            |
+| `labtab labs list`             | Labs you have membership in               |
+| `labtab grants list`           | Grants, filter by `--status`              |
+| `labtab grants show <id>`      | Grant detail card                         |
+| `labtab papers list`           | Papers, filter by `--year`                |
+| `labtab papers show <id>`      | Paper detail with authors, DOI            |
+| `labtab meetings upcoming`     | Meetings in the next `--days` (default 7) |
+| `labtab meetings show <id>`    | Meeting detail card                       |
+| `labtab tasks list`            | Tasks, filter by `--status`               |
+| `labtab tasks show <id>`       | Task detail card                          |
+| `labtab projects list`         | Projects                                  |
+| `labtab projects show <id>`    | Project detail card                       |
+| `labtab people list`           | Lab members                               |
+| `labtab people show <id>`      | Person detail card                        |
+| `labtab export`                | Download a full lab export                |
+
+## Configuration
+
+`labtab` reads and writes its config at `~/.config/labtab/config.toml`.
+Override the path with the `LABTAB_CONFIG_FILE` environment variable.
+
+```toml
+[api]
+base_url = "https://labtab.app/api/v1"
+
+[auth]
+api_key = "lab_api_xxxxxxxx"
+user_email = "pi@example.com"
+default_lab_id = 42
+default_lab_slug = "chen-neuro-lab"
+```
+
+The config file is written with `0600` permissions so other users on the
+machine cannot read your API key.
+
+If you later move the product domain, you can rewrite just the hostname while
+preserving the rest of the API path:
+
+```bash
+labtab auth set-base-url --host labtab.io
+```
+
+## Pydantic models
+
+The package ships two sets of models:
+
+* `labtab.models` (re-exports `labtab.models.api`) — hand-curated, **lenient**
+  models the CLI uses internally. They tolerate extra or renamed backend
+  fields so a CLI install doesn't break when the server ships new columns.
+* `labtab.models.generated` — a **strict**, auto-generated snapshot of the
+  backend's OpenAPI schema. Useful if you want to script against the API
+  directly with precise types.
+
+### Regenerating the strict snapshot
+
+```bash
+# with a running backend at localhost:8000
+datamodel-codegen \
+  --url http://localhost:8000/api/v1/schema/ \
+  --output src/labtab/models/generated.py \
+  --output-model-type pydantic_v2.BaseModel \
+  --input-file-type openapi
+
+# or from a snapshotted schema
+cd backend && python manage.py spectacular --file /tmp/schema.yml
+datamodel-codegen --input /tmp/schema.yml \
+  --output src/labtab/models/generated.py \
+  --output-model-type pydantic_v2.BaseModel \
+  --input-file-type openapi
+```
+
+## License
+
+MIT. See `LICENSE`.

labtab-0.1.0/RELEASING.md

@@ -0,0 +1,144 @@
+# Releasing `labtab`
+
+This document describes how to cut a release of the LabTab CLI Python
+package and ship it to PyPI (or Test PyPI for pre-releases).
+
+## Prerequisites
+
+### Trusted Publishing configuration
+
+Release automation lives in
+[`.github/workflows/cli-release.yml`](../../.github/workflows/cli-release.yml)
+and uses PyPI Trusted Publishing via GitHub Actions OIDC. That means:
+
+- no long-lived `PYPI_API_TOKEN` / `TEST_PYPI_API_TOKEN` secrets are needed
+- the **first** upload can create the `labtab` project if you configure a
+  **pending publisher** first
+
+Configure **two** pending publishers before the first tagged release:
+
+1. On **PyPI** (`https://pypi.org`), go to **Account settings -> Publishing**
+   and add a **GitHub Actions** publisher for:
+   - owner: `alexharston`
+   - repository name: `labtab`
+   - workflow name: `cli-release.yml`
+   - environment name: `pypi`
+   - project name: `labtab`
+2. On **TestPyPI** (`https://test.pypi.org`), repeat the same setup but use:
+   - environment name: `testpypi`
+   - project name: `labtab`
+
+Official docs:
+
+- https://docs.pypi.org/trusted-publishers/
+- https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
+
+The workflow also references two GitHub *environments* (`pypi` and
+`testpypi`) so required reviewers / branch protections can be attached
+if desired. Both are optional - an empty environment works.
+
+Important: a pending publisher does **not** reserve the package name until the
+first publish actually happens. If `labtab` is still free and you want to claim
+it, create the pending publisher(s) and cut the release promptly.
+
+### Local tooling
+
+You only need the release tooling locally if you want to test the
+build before pushing the tag:
+
+```bash
+cd backend/labtab_cli
+python -m pip install --upgrade build twine
+python -m build --sdist --wheel
+twine check dist/*
+```
+
+## Release steps
+
+1. **Bump the version** in
+   [`backend/labtab_cli/pyproject.toml`](./pyproject.toml) (the
+   `[project].version` field). Follow PEP 440:
+   - `0.1.0` - stable release.
+   - `0.1.0rc1`, `0.1.0a2`, `0.1.0b1` - pre-releases (candidate,
+     alpha, beta). These ship to **Test PyPI** only.
+2. **Commit** the version bump:
+   ```bash
+   git add backend/labtab_cli/pyproject.toml
+   git commit -m "chore(cli): bump labtab to 0.1.0"
+   ```
+3. **Tag** the commit with the `labtab/` namespace:
+   ```bash
+   git tag labtab/v0.1.0
+   ```
+   For pre-releases: `git tag labtab/v0.1.0rc1` etc.
+4. **Push** the branch + tag:
+   ```bash
+   git push origin HEAD
+   git push origin labtab/v0.1.0
+   ```
+5. **Watch the workflow** run in the **Actions** tab. The `build`
+   job produces and twine-checks the artefacts; the `pypi` or
+   `testpypi` job (one of the two, based on the tag) uploads.
+
+Tag format reference:
+
+| Tag | Destination |
+| --- | --- |
+| `labtab/v0.1.0` | pypi.org |
+| `labtab/v0.1.1` | pypi.org |
+| `labtab/v0.2.0rc1` | test.pypi.org |
+| `labtab/v0.2.0a1` | test.pypi.org |
+| `labtab/v0.2.0b1` | test.pypi.org |
+
+## Verifying a release
+
+### From Test PyPI
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            labtab==0.2.0rc1
+labtab --help
+```
+
+The `--extra-index-url` fallback is important - Test PyPI does not
+mirror all dependencies, so pip needs the real PyPI as a fallback
+for transitive deps (typer, httpx, ...).
+
+### From PyPI
+
+```bash
+pip install labtab==0.1.0
+labtab --help
+```
+
+## Rollback
+
+PyPI does **not** allow un-publishing a version once it has been
+uploaded. If a broken release ships:
+
+1. **Yank** the release through the PyPI UI:
+   https://pypi.org/manage/project/labtab/ -> "Yank" a release.
+   Yanked releases remain installable by exact pin but are skipped by
+   the resolver by default. This is usually enough to stop new
+   installs from picking up the bad version.
+2. **Ship a new patch release** with the fix (e.g. bump `0.1.0` to
+   `0.1.1`) following the release steps above. Never try to re-upload
+   the same version number - PyPI will reject duplicate filenames.
+3. **Test PyPI releases** can be yanked the same way at
+   https://test.pypi.org/manage/project/labtab/.
+
+## FAQ
+
+- *The workflow says "non-user identities cannot create new projects"* - the
+  pending publisher is missing or does not match the repository, workflow,
+  environment, or project name exactly.
+- *The workflow says "File already exists"* - this means the version
+  number was already uploaded. Bump to a new version and tag again.
+- *A pre-release tag ended up on PyPI* - double-check the tag matches
+  `rc`/`a`/`b` at the end. The workflow's branch logic in
+  `cli-release.yml` ("Derive version + channel from tag") routes the
+  job based on that pattern.
+- *I want a local dry run of the release* - run the build + twine
+  check commands from the Local tooling section above. `twine check`
+  catches most metadata / README rendering issues before you tag.

labtab-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "labtab"
+version = "0.1.0"
+description = "Command-line interface for LabTab (Wetware Ltd). Manage your lab from the terminal."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "Wetware Ltd", email = "support@wetware.ai"}]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "typer[all]>=0.12.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.5",
+    "pydantic[email]>=2.5",
+    "rich>=13.7.0",
+    "tomli>=2.0 ; python_version<'3.11'",
+    "tomli-w>=1.0",
+]
+
+[project.scripts]
+labtab = "labtab.cli:app"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4", "pytest-httpx>=0.30", "responses>=0.24", "ruff>=0.1"]
+
+[build-system]
+requires = ["setuptools>=65", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+labtab = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "UP"]
+ignore = ["E501"]

labtab-0.1.0/setup.cfg

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

labtab-0.1.0/src/labtab/__init__.py

@@ -0,0 +1,5 @@
+"""labtab — command-line interface for LabTab (Wetware Ltd)."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

labtab-0.1.0/src/labtab/auth.py

@@ -0,0 +1,178 @@
+"""Device-pairing primitives for the labtab CLI.
+
+The flow implemented by this module is:
+
+1. ``POST /cli/pair/start/`` with ``{client_info: {user_agent, hostname}}``.
+2. The server returns ``{pairing_code, confirm_url, expires_in}``.
+3. The user opens ``confirm_url`` in their browser (we try to open it for them
+   via :mod:`webbrowser`) and approves the pairing.
+4. Meanwhile the CLI polls ``GET /cli/pair/poll/?code=<pairing_code>`` every
+   ``poll_interval`` seconds. On ``status == "confirmed"`` the server returns
+   an API key plus a user profile which we persist to the config file.
+5. If the server reports ``expired`` or ``denied``, or we exceed ``timeout``
+   seconds of polling, we raise :class:`PairingError`.
+
+Agent L's backend endpoints are what we consume here. Until those endpoints
+land, tests mock the HTTP responses via :mod:`pytest_httpx`.
+"""
+
+from __future__ import annotations
+
+import platform
+import socket
+import time
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from . import __version__
+from .client import LabtabClient
+from .config import Config
+from .errors import APIError, PairingError
+from .models import CLIPairConfirm, CLIPairStart
+
+DEFAULT_POLL_INTERVAL = 2.0
+DEFAULT_TIMEOUT_SECONDS = 600  # 10 minutes
+
+
+def client_info() -> dict[str, str]:
+    """Metadata sent to ``/cli/pair/start/`` so users can identify a terminal."""
+
+    return {
+        "user_agent": f"labtab/{__version__} ({platform.system().lower()})",
+        "hostname": socket.gethostname(),
+    }
+
+
+@dataclass
+class PairingResult:
+    """Result of a successful pairing — used to populate the config."""
+
+    api_key: str
+    user_email: str | None
+    default_lab_id: int | None
+    default_lab_slug: str | None
+
+
+def start_pairing(client: LabtabClient) -> CLIPairStart:
+    """Initiate the pairing flow. Does not require authentication."""
+
+    payload = client.request(
+        "POST",
+        "/cli/pair/start/",
+        json={"client_info": client_info()},
+        require_auth=False,
+    )
+    try:
+        return CLIPairStart.model_validate(payload)
+    except Exception as exc:  # pragma: no cover - validation details
+        raise PairingError(f"Unexpected response from /cli/pair/start/: {exc}") from exc
+
+
+def poll_pairing(client: LabtabClient, code: str) -> CLIPairConfirm:
+    """Poll once for the pairing status."""
+
+    payload = client.request(
+        "GET",
+        "/cli/pair/poll/",
+        params={"code": code},
+        require_auth=False,
+    )
+    try:
+        return CLIPairConfirm.model_validate(payload)
+    except Exception as exc:  # pragma: no cover - validation details
+        raise PairingError(f"Unexpected response from /cli/pair/poll/: {exc}") from exc
+
+
+def maybe_open_browser(url: str, *, enabled: bool) -> None:
+    """Open ``url`` in the default browser unless ``enabled`` is False."""
+
+    if not enabled:
+        return
+    try:
+        webbrowser.open(url)
+    except webbrowser.Error:  # pragma: no cover - platform specific
+        pass
+
+
+def run_pairing(
+    client: LabtabClient,
+    *,
+    open_browser: bool = True,
+    poll_interval: float = DEFAULT_POLL_INTERVAL,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    on_start: Callable[[CLIPairStart], None] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    now: Callable[[], float] = time.monotonic,
+) -> PairingResult:
+    """Drive the full pairing flow.
+
+    ``on_start`` is called once with the start payload so callers can print the
+    confirmation URL and code. ``sleep`` and ``now`` are injectable for tests.
+    """
+
+    try:
+        start = start_pairing(client)
+    except APIError as exc:
+        raise PairingError(f"Could not start pairing: {exc.message}") from exc
+
+    if on_start is not None:
+        on_start(start)
+    maybe_open_browser(start.confirm_url, enabled=open_browser)
+
+    deadline = now() + min(timeout, start.expires_in or timeout)
+
+    while True:
+        try:
+            poll = poll_pairing(client, start.pairing_code)
+        except APIError as exc:
+            raise PairingError(f"Pairing poll failed: {exc.message}") from exc
+
+        status = (poll.status or "").lower()
+        if status == "confirmed":
+            if not poll.api_key:
+                raise PairingError(
+                    "Pairing confirmed but server did not return an API key.",
+                )
+            return PairingResult(
+                api_key=poll.api_key,
+                user_email=poll.user_email,
+                default_lab_id=poll.default_lab_id,
+                default_lab_slug=poll.default_lab_slug,
+            )
+        if status == "expired":
+            raise PairingError("Pairing code expired. Run `labtab auth login` again.")
+        if status == "denied":
+            raise PairingError("Pairing was denied in the browser.")
+
+        if now() >= deadline:
+            raise PairingError(
+                "Timed out waiting for browser confirmation. Run `labtab auth login` again.",
+            )
+
+        sleep(poll_interval)
+
+
+def persist_pairing(config: Config, result: PairingResult) -> Config:
+    """Write ``result`` into ``config`` and save to disk."""
+
+    config.api_key = result.api_key
+    config.user_email = result.user_email
+    config.default_lab_id = result.default_lab_id
+    config.default_lab_slug = result.default_lab_slug
+    config.save()
+    return config
+
+
+def summarise_identity(config: Config) -> dict[str, Any]:
+    """Return a plain dict describing the current signed-in identity."""
+
+    return {
+        "signed_in": bool(config.api_key),
+        "user_email": config.user_email,
+        "default_lab_id": config.default_lab_id,
+        "default_lab_slug": config.default_lab_slug,
+        "base_url": config.base_url,
+        "config_path": str(config.path),
+    }