Add justfile with op integration, restrict workflow permissions

Adds a justfile wrapping common tasks, with 1Password CLI injecting
secrets for integration tests. Adds explicit permissions blocks to all
GitHub Actions workflows to restrict GITHUB_TOKEN scope. Updates README
development docs to reflect just-based workflow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: vdavez

.github/workflows/lint.yml

@@ -9,6 +9,9 @@ on:
   # pull_request:
   #   branches: [ main, develop ]
 
+permissions:
+  contents: read
+
 jobs:
   lint:
     runs-on: ubuntu-latest

.github/workflows/publish.yml

@@ -5,6 +5,10 @@ on:
     types: [published]
   workflow_dispatch:
 
+permissions:
+  contents: read
+  id-token: write
+
 jobs:
   build-and-publish:
     runs-on: ubuntu-latest

.github/workflows/security.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [ main, develop ]
 
+permissions:
+  contents: read
+
 jobs:
   bandit:
     runs-on: ubuntu-latest

.github/workflows/test.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [ main, develop ]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ${{ matrix.os }}

README.md

@@ -346,7 +346,7 @@ print(contract["recipient"]["display_name"])  # Nested fields too
 
 ## Development
 
-This project uses [uv](https://docs.astral.sh/uv/) for dependency management and tooling.
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management and [just](https://github.com/casey/just) as a task runner. Integration tests use [1Password CLI](https://developer.1password.com/docs/cli/) (`op`) to inject the API key at runtime.
 
 ### Setup
 
@@ -357,11 +357,19 @@ cd tango-python
 
 # Install dependencies with uv
 uv sync --all-extras
+```
+
+### Secrets Management
+
+API keys are stored in 1Password and injected at runtime via `op run`. The `.env` file uses secret references instead of real values:
 
-# Or install dev dependencies only
-uv sync --group dev
+```bash
+# .env
+TANGO_API_KEY=op://Vault/tango-api/credential
 ```
 
+Recipes that need the API key (integration tests, live tests, cassette refresh) handle this automatically through `just`.
+
 ### Testing
 
 The SDK includes a comprehensive test suite with:
@@ -370,23 +378,19 @@ The SDK includes a comprehensive test suite with:
 
 ```bash
 # Run all tests
-uv run pytest
+just test
 
 # Run only unit tests
-uv run pytest tests/ -m "not integration"
+just test-unit
 
-# Run only integration tests
-uv run pytest tests/integration/
+# Run integration tests (API key injected via 1Password)
+just test-integration
 
-# Run integration tests with live API (requires TANGO_API_KEY)
-export TANGO_API_KEY=your-api-key
-export TANGO_USE_LIVE_API=true
-uv run pytest tests/integration/
+# Run integration tests with live API
+just test-live
 
 # Refresh cassettes with fresh API responses
-export TANGO_API_KEY=your-api-key
-export TANGO_REFRESH_CASSETTES=true
-uv run pytest tests/integration/
+just refresh-cassettes
 ```
 
 See [tests/integration/README.md](tests/integration/README.md) for detailed testing documentation.
@@ -395,16 +399,19 @@ See [tests/integration/README.md](tests/integration/README.md) for detailed test
 
 ```bash
 # Format code
-uv run ruff format tango/
+just fmt
 
 # Lint code
-uv run ruff check tango/
+just lint
 
 # Type checking
-uv run mypy tango/
+just typecheck
+
+# Security scan
+just bandit
 
-# Run all checks
-uv run ruff format tango/ && uv run ruff check tango/ && uv run mypy tango/
+# Run all checks (format, lint, typecheck, bandit)
+just check
 ```
 
 ### Project Structure
@@ -482,6 +489,8 @@ tango-python/
 
 - Python 3.12 or higher
 - httpx >= 0.27.0
+- [just](https://github.com/casey/just) (for development task runner)
+- [1Password CLI](https://developer.1password.com/docs/cli/) (for integration tests)
 
 ## License
 
@@ -501,12 +510,9 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Run lint and format: `uv run ruff format tango/ && uv run ruff check tango/`
-4. Run type checking: `uv run mypy tango/`
-5. Run tests: `uv run pytest`
-6. (Optional) Run [filter and shape conformance](scripts/README.md#filter-and-shape-conformance) if you have the tango API manifest; CI will run it on push/PR
-7. Commit your changes (`git commit -m 'Add amazing feature'`)
-8. Push to the branch (`git push origin feature/amazing-feature`)
-9. Open a Pull Request
-
-For a single command that runs formatting, linting, type checking, and tests (and conformance when the manifest is present), use: `uv run python scripts/pr_review.py --mode full`
+3. Run all checks: `just check`
+4. Run tests: `just test`
+5. (Optional) Run full PR review: `just pr-review`
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request

justfile

@@ -0,0 +1,49 @@
+# Tango Python SDK task runner
+# Requires: just (https://github.com/casey/just), uv, op (1Password CLI)
+
+# Default: list available recipes
+default:
+    @just --list
+
+# Run all tests
+test *args:
+    uv run pytest {{ args }}
+
+# Run unit tests only
+test-unit *args:
+    uv run pytest tests/ -m "not integration" {{ args }}
+
+# Run integration tests (requires API key in 1Password)
+test-integration *args:
+    op run --env-file .env -- uv run pytest tests/integration/ {{ args }}
+
+# Run integration tests with live API
+test-live *args:
+    TANGO_USE_LIVE_API=true op run --env-file .env -- uv run pytest tests/integration/ {{ args }}
+
+# Refresh VCR cassettes with fresh API responses
+refresh-cassettes *args:
+    TANGO_REFRESH_CASSETTES=true op run --env-file .env -- uv run pytest tests/integration/ {{ args }}
+
+# Format code
+fmt:
+    uv run ruff format tango/
+
+# Lint code
+lint:
+    uv run ruff check tango/
+
+# Type checking
+typecheck:
+    uv run mypy tango/
+
+# Security scan with bandit
+bandit:
+    uv run bandit -r tango/ -c pyproject.toml
+
+# Run all code quality checks
+check: fmt lint typecheck bandit
+
+# Full PR review (format, lint, types, tests, conformance)
+pr-review *args:
+    uv run python scripts/pr_review.py --mode full {{ args }}