feat: initial Python SDK workspace

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    name: Lint + Test (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node (for @archastro/channel-harness + prism)
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+
+      - name: Setup Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install project + dev deps
+        run: uv sync --all-extras
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
+      - name: Unit tests
+        run: uv run pytest tests/test_http_client.py src/phx_channel/tests/test_unit.py
+
+      - name: Harness-client integration tests
+        run: uv run pytest tests/harness
+
+      - name: Contract tests (REST + channels over real harness subprocess)
+        run: uv run pytest tests/contract
+        env:
+          ARCHASTRO_RUN_CHANNEL_CONTRACT_TESTS: "1"

.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.venv/
+
+# Node tooling (for @archastro/channel-harness + prism)
+node_modules/
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/

README.md

@@ -0,0 +1,86 @@
+# archastro-python
+
+Python SDK for the ArchAstro Platform API.
+
+```bash
+uv add archastro-platform-sdk      # or: pip install archastro-platform-sdk
+```
+
+```python
+from archastro import ArchAstro
+
+client = ArchAstro(api_key="pk_...")
+teams = client.v1.teams.list()
+```
+
+## Packages
+
+- **`archastro`** — typed REST + channel SDK generated from the canonical
+  OpenAPI spec at [`ArchAstro/archastro-openapi`](https://github.com/ArchAstro/archastro-openapi).
+  Pydantic models, async channel classes, auth helpers.
+- **`phx_channel`** — the hand-written Phoenix Channels client the
+  generated channel classes run on top of. WebSocket transport, join /
+  reply / push / leave, heartbeat, reconnect, and a `HarnessServiceClient`
+  for driving the
+  [`@archastro/channel-harness`](https://www.npmjs.com/package/@archastro/channel-harness)
+  service from Python tests.
+
+## Development
+
+This repo contains:
+
+- Python SDK (`src/archastro/`, `src/phx_channel/`) installed via `uv`
+- JS tooling (`package.json`) — the channel-harness subprocess that
+  powers the channel contract tests, plus the Prism mock server that
+  backs the REST contract tests. Installed via `npm ci`.
+
+### Setup
+
+```bash
+npm ci           # channel-harness + prism (for contract tests)
+uv sync          # Python deps + dev deps (pytest, ruff)
+```
+
+### Running tests
+
+```bash
+# Unit tests only (no external services needed)
+uv run pytest tests/test_http_client.py tests/test_synthetic.py src/phx_channel/tests/unit.test.py
+
+# REST contract tests (spawns Prism mock server)
+uv run pytest tests/contract
+
+# REST + channel contract tests (also spawns channel-harness subprocess)
+ARCHASTRO_RUN_CHANNEL_CONTRACT_TESTS=1 uv run pytest tests/contract
+```
+
+### Regenerating the SDK
+
+The typed SDK — `src/archastro/platform/` and `tests/contract/` — is
+regenerated from the canonical OpenAPI spec by
+[`@archastro/sdk-generator`](https://www.npmjs.com/package/@archastro/sdk-generator).
+Don't hand-edit files with the `auto-generated by @archastro/sdk-generator`
+header; they'll be overwritten.
+
+```bash
+./scripts/regenerate_sdk.sh
+```
+
+The script fetches the spec from `ArchAstro/archastro-openapi@main` and
+runs the generator via `npx`. Knobs:
+
+- `ARCHASTRO_OPENAPI_REF=some-branch ./scripts/regenerate_sdk.sh` — pull
+  the spec from a non-default ref (useful when a spec change is on a
+  branch awaiting merge).
+- `ARCHASTRO_SDK_GENERATOR=@archastro/sdk-generator@0.1.0 ./scripts/regenerate_sdk.sh`
+  — pin the generator version for a release branch.
+
+After regenerating, review the diff, run the full test suite, and commit.
+
+## Release
+
+```bash
+# bump version in pyproject.toml, then:
+uv build
+uv publish
+```