treinta-previews 0.1.0__tar.gz

treinta_previews-0.1.0/.gitignore

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

treinta_previews-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `treinta-previews` are documented here. This project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-07-01
+
+Initial release. 1:1 parity with the Node SDK (`cli/client.ts` + `web/src/lib/api.ts`).
+
+### Added
+- Synchronous `PreviewsClient` and asynchronous `AsyncPreviewsClient`.
+- Resources: `vms`, `snapshots`, `drives`, `integrations`, `detect`, `accounts`, `system`.
+- VM lifecycle: `create`, `list`, `get`, `destroy`, `restart`, `redeploy`,
+  `run`, `logs` (SSE), `get_env`, `set_env`, `bandwidth`, `persist`,
+  `unpersist`, `rename_slug`, `slug_available`, `upload_files`,
+  `mint_widget_token`, `wait_until_running`, `create_from_folder`.
+- Folder → zip archiving (`archive.zip_directory`) faithful to `mcp/src/archive.ts`:
+  honors `.gitignore` via `git ls-files`, strips secrets, force-includes
+  `.env.example`, 50 MiB compressed cap, uncompressed tripwire, fingerprint cache.
+- SSE parsing for named-event logs and unnamed detect streams.
+- Frozen-dataclass models with `from_dict` (camelCase → snake_case, tolerant of
+  unknown keys) and a shipped `py.typed` marker.
+- Backend widget proxy (`previews.proxy`) with FastAPI and Flask adapters.

treinta_previews-0.1.0/LICENSE

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

treinta_previews-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: treinta-previews
+Version: 0.1.0
+Summary: Python SDK for the Propie / Previews VM-as-a-Service platform (Firecracker microVMs).
+Project-URL: Homepage, https://previews.amapola.treinta.ai
+Project-URL: Repository, https://github.com/justfedec/previews
+Author-email: Treinta Previews <carrizofg@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: firecracker,microvm,previews,propie,sdk,vm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: anyio; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.2; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# treinta-previews (Python SDK)
+
+Python SDK for the **Propie / Previews** VM-as-a-Service platform — launch
+Firecracker microVMs from a git repo or a local folder, run commands, stream
+logs, attach drives and databases, take snapshots, promote to permanent
+(scale-to-zero) previews, and embed a browser widget safely.
+
+It mirrors the Node SDK (`cli/client.ts` + `web/src/lib/api.ts`) 1:1 in surface
+and naming, translated to Pythonic snake_case.
+
+## Install
+
+```bash
+pip install treinta-previews
+```
+
+- **Distribution name:** `treinta-previews`
+- **Import name:** `previews`
+
+```python
+from previews import PreviewsClient
+```
+
+> If the top-level name `previews` ever collides with another package in your
+> environment, the intended fallback import name is `treinta_previews`. This
+> release publishes the package as `previews`; use a virtualenv to avoid
+> collisions.
+
+Optional extras:
+
+```bash
+pip install "treinta-previews[fastapi]"   # widget proxy FastAPI adapter
+pip install "treinta-previews[flask]"     # widget proxy Flask adapter
+```
+
+## Authentication
+
+The client resolves credentials from arguments or the environment:
+
+| Setting  | Argument   | Env vars (in precedence order)                                        | Default |
+| -------- | ---------- | -------------------------------------------------------------------- | ------- |
+| API key  | `api_key`  | `TREINTA_PREVIEWS_API_KEY`, `PROPIE_API_KEY`, `PREVIEWS_API_KEY`     | —       |
+| Base URL | `base_url` | `TREINTA_PREVIEWS_API_URL`, `PROPIE_API_URL`                        | `https://previews.amapola.treinta.ai/api` |
+
+Keys look like `pvk_<prefix>_<secret>` and are sent as `Authorization: Bearer pvk_...`.
+
+## Quick start
+
+```python
+from previews import PreviewsClient
+
+with PreviewsClient() as client:            # api key from env
+    vm = client.vms.create(
+        repo_url="https://github.com/owner/repo",
+        stack="node20",
+        exposed_port=3000,
+        environment_variables={"NODE_ENV": "production"},
+    )
+    vm = client.vms.wait_until_running(vm.id)
+    print(vm.url)
+
+    result = client.vms.run(vm.id, "npm test")
+    print(result.exit_code, result.stdout)
+
+    for event in client.vms.logs(vm.id, follow=False):
+        print(event.message)
+
+    client.vms.destroy(vm.id)
+```
+
+Deploy a local folder (zipped locally, honoring `.gitignore`, stripping secrets):
+
+```python
+det = client.detect.folder("/path/to/app")           # SSE stack detection
+vm = client.vms.create_from_folder(
+    "/path/to/app",
+    stack=det.stack,
+    start_command=det.start_command,
+    exposed_port=det.exposed_port,
+)
+```
+
+### Async
+
+```python
+from previews import AsyncPreviewsClient
+
+async with AsyncPreviewsClient() as client:
+    vms = await client.vms.list()
+    async for event in client.vms.logs(vms[0].id, follow=False):
+        print(event.message)
+```
+
+## API surface
+
+`PreviewsClient(api_key=None, *, base_url=None, timeout=30.0, http_client=None)`
+(and the identical `AsyncPreviewsClient` with `await`/async generators/`aclose()`).
+Both are context managers and expose `request(method, path, *, json=None, ...)`
+plus the resources below.
+
+### `client.vms`
+
+| Method | REST |
+| --- | --- |
+| `create(**fields)` | `POST /vms` (json) |
+| `create_from_folder(path, **meta)` / `create_from_zip(zip_bytes, **meta)` | `POST /vms` (multipart) |
+| `list()` | `GET /vms` |
+| `get(id)` | `GET /vms/:id` |
+| `destroy(id)` | `DELETE /vms/:id` |
+| `restart(id)` | `POST /vms/:id/restart` |
+| `redeploy(id)` | `POST /vms/:id/redeploy` |
+| `run(id, command, *, timeout=300.0)` | `POST /vms/:id/run` (buffered) |
+| `logs(id, *, follow=True)` | `GET /vms/:id/logs` (SSE) → `Iterator[LogEvent]` |
+| `get_env(id)` / `set_env(id, env)` | `GET`/`PUT /vms/:id/env` |
+| `bandwidth(id)` | `GET /vms/:id/bandwidth` |
+| `persist(id, slug)` / `unpersist(id)` / `rename_slug(id, slug)` | `/vms/:id/persist`, `/vms/:id/slug` |
+| `slug_available(slug)` → `(bool, reason?)` | `GET /vms/slug-available` |
+| `upload_files(id, files, *, base_dir="/app")` | `POST /vms/:id/files` |
+| `mint_widget_token(id, *, capabilities=None, ttl_seconds=None)` | `POST /vms/:id/widget-token` |
+| `wait_until_running(id, *, timeout=300.0, interval=2.0, on_status=None)` | polls `GET /vms/:id` |
+
+`create` / `create_from_*` accept snake_case fields: `repo_url`, `stack`,
+`branch`, `subdirectory`, `exposed_port`, `install_command`, `start_command`,
+`environment_variables`, `drive_id`, `drive_mount_path`, `drive_read_only`,
+`database_integration_id`, `vcpus`, `memory_mib`, `persistent`, `slug`.
+
+### `client.snapshots` / `.drives` / `.integrations` / `.detect` / `.accounts`
+
+- `snapshots.list() / create(vm_id, name=None) / clone(snapshot_id, *, name=None, environment_variables=None) / delete(snapshot_id)`
+- `drives.list() / create(name, size_gib, *, mount_path=None) / delete(id)`
+- `integrations.list() / create(**fields) / delete(id)`
+- `detect.public(repo_url, *, on_progress=None) / zip(zip_bytes, ...) / folder(path, ...)`
+- `accounts.current()` → `CurrentPrincipal(account, project, auth_type, api_key)`
+
+### System status
+
+Not a dedicated resource; use the generic request helper:
+
+```python
+from previews import SystemStatus
+status = SystemStatus.from_dict(client.request("GET", "/system/status"))
+print(status.caches["npm"].size_bytes)
+```
+
+## Errors
+
+Non-2xx responses raise `PreviewsApiError(status, code, message)` from the
+`{ error: { code, message } }` envelope (a non-JSON body yields code `UNKNOWN`).
+`wait_until_running` raises `PreviewsTimeoutError` on deadline. Missing
+credentials raise `PreviewsConfigError`.
+
+## Models
+
+Responses are frozen dataclasses with a tolerant `from_dict` (camelCase →
+snake_case, unknown keys ignored): `Preview` (alias `VM`), `RunCommandResult`,
+`VMSnapshot`, `DetectionResult`/`EnvVarHint`, `BandwidthSample`/`BandwidthResponse`,
+`Account`/`Project`/`ApiKeyRef`/`CurrentPrincipal`, `DatabaseIntegration`,
+`Drive`, `SystemStatus`/`CacheStat`, `WidgetToken`, `UploadResult`, `LogEvent`.
+The package ships `py.typed`.
+
+## Widget backend proxy
+
+The React widget UI is built separately. This SDK provides the backend piece.
+
+**Scoped token (recommended):** mint a short-lived `pwt_` token server-side and
+hand it to the browser, which then calls the platform directly.
+
+```python
+token = client.vms.mint_widget_token(vm_id, capabilities=["preview:read", "vm:run"])
+```
+
+**Backend proxy:** the browser calls *your* server; the proxy forwards only a
+whitelisted subset of operations to the platform using the `pvk_` key it holds —
+the key never reaches the browser.
+
+```python
+from previews import PreviewsClient
+from previews.proxy import PreviewsProxy, ProxyConfig, make_router  # or make_blueprint
+
+client = PreviewsClient()
+proxy = PreviewsProxy(ProxyConfig(
+    client=client,
+    allowed_origins=["https://app.example.com"],
+    allowed_vm_ids={"<vm-uuid>"},          # None = any VM in the project
+    # allow_ops defaults to WIDGET_SAFE_OPS = {"status","run","files","logs","mint_token"}
+))
+
+# FastAPI
+from fastapi import FastAPI
+app = FastAPI()
+app.include_router(make_router(proxy, prefix="/previews"))
+
+# Flask
+# from flask import Flask
+# app = Flask(__name__)
+# app.register_blueprint(make_blueprint(proxy, url_prefix="/previews"))
+```
+
+The proxy enforces the origin allowlist, the op whitelist (hard-capped to the
+widget-safe set), and the per-VM restriction; it never echoes the `pvk_` key.
+
+## License
+
+MIT

treinta_previews-0.1.0/README.md

@@ -0,0 +1,204 @@
+# treinta-previews (Python SDK)
+
+Python SDK for the **Propie / Previews** VM-as-a-Service platform — launch
+Firecracker microVMs from a git repo or a local folder, run commands, stream
+logs, attach drives and databases, take snapshots, promote to permanent
+(scale-to-zero) previews, and embed a browser widget safely.
+
+It mirrors the Node SDK (`cli/client.ts` + `web/src/lib/api.ts`) 1:1 in surface
+and naming, translated to Pythonic snake_case.
+
+## Install
+
+```bash
+pip install treinta-previews
+```
+
+- **Distribution name:** `treinta-previews`
+- **Import name:** `previews`
+
+```python
+from previews import PreviewsClient
+```
+
+> If the top-level name `previews` ever collides with another package in your
+> environment, the intended fallback import name is `treinta_previews`. This
+> release publishes the package as `previews`; use a virtualenv to avoid
+> collisions.
+
+Optional extras:
+
+```bash
+pip install "treinta-previews[fastapi]"   # widget proxy FastAPI adapter
+pip install "treinta-previews[flask]"     # widget proxy Flask adapter
+```
+
+## Authentication
+
+The client resolves credentials from arguments or the environment:
+
+| Setting  | Argument   | Env vars (in precedence order)                                        | Default |
+| -------- | ---------- | -------------------------------------------------------------------- | ------- |
+| API key  | `api_key`  | `TREINTA_PREVIEWS_API_KEY`, `PROPIE_API_KEY`, `PREVIEWS_API_KEY`     | —       |
+| Base URL | `base_url` | `TREINTA_PREVIEWS_API_URL`, `PROPIE_API_URL`                        | `https://previews.amapola.treinta.ai/api` |
+
+Keys look like `pvk_<prefix>_<secret>` and are sent as `Authorization: Bearer pvk_...`.
+
+## Quick start
+
+```python
+from previews import PreviewsClient
+
+with PreviewsClient() as client:            # api key from env
+    vm = client.vms.create(
+        repo_url="https://github.com/owner/repo",
+        stack="node20",
+        exposed_port=3000,
+        environment_variables={"NODE_ENV": "production"},
+    )
+    vm = client.vms.wait_until_running(vm.id)
+    print(vm.url)
+
+    result = client.vms.run(vm.id, "npm test")
+    print(result.exit_code, result.stdout)
+
+    for event in client.vms.logs(vm.id, follow=False):
+        print(event.message)
+
+    client.vms.destroy(vm.id)
+```
+
+Deploy a local folder (zipped locally, honoring `.gitignore`, stripping secrets):
+
+```python
+det = client.detect.folder("/path/to/app")           # SSE stack detection
+vm = client.vms.create_from_folder(
+    "/path/to/app",
+    stack=det.stack,
+    start_command=det.start_command,
+    exposed_port=det.exposed_port,
+)
+```
+
+### Async
+
+```python
+from previews import AsyncPreviewsClient
+
+async with AsyncPreviewsClient() as client:
+    vms = await client.vms.list()
+    async for event in client.vms.logs(vms[0].id, follow=False):
+        print(event.message)
+```
+
+## API surface
+
+`PreviewsClient(api_key=None, *, base_url=None, timeout=30.0, http_client=None)`
+(and the identical `AsyncPreviewsClient` with `await`/async generators/`aclose()`).
+Both are context managers and expose `request(method, path, *, json=None, ...)`
+plus the resources below.
+
+### `client.vms`
+
+| Method | REST |
+| --- | --- |
+| `create(**fields)` | `POST /vms` (json) |
+| `create_from_folder(path, **meta)` / `create_from_zip(zip_bytes, **meta)` | `POST /vms` (multipart) |
+| `list()` | `GET /vms` |
+| `get(id)` | `GET /vms/:id` |
+| `destroy(id)` | `DELETE /vms/:id` |
+| `restart(id)` | `POST /vms/:id/restart` |
+| `redeploy(id)` | `POST /vms/:id/redeploy` |
+| `run(id, command, *, timeout=300.0)` | `POST /vms/:id/run` (buffered) |
+| `logs(id, *, follow=True)` | `GET /vms/:id/logs` (SSE) → `Iterator[LogEvent]` |
+| `get_env(id)` / `set_env(id, env)` | `GET`/`PUT /vms/:id/env` |
+| `bandwidth(id)` | `GET /vms/:id/bandwidth` |
+| `persist(id, slug)` / `unpersist(id)` / `rename_slug(id, slug)` | `/vms/:id/persist`, `/vms/:id/slug` |
+| `slug_available(slug)` → `(bool, reason?)` | `GET /vms/slug-available` |
+| `upload_files(id, files, *, base_dir="/app")` | `POST /vms/:id/files` |
+| `mint_widget_token(id, *, capabilities=None, ttl_seconds=None)` | `POST /vms/:id/widget-token` |
+| `wait_until_running(id, *, timeout=300.0, interval=2.0, on_status=None)` | polls `GET /vms/:id` |
+
+`create` / `create_from_*` accept snake_case fields: `repo_url`, `stack`,
+`branch`, `subdirectory`, `exposed_port`, `install_command`, `start_command`,
+`environment_variables`, `drive_id`, `drive_mount_path`, `drive_read_only`,
+`database_integration_id`, `vcpus`, `memory_mib`, `persistent`, `slug`.
+
+### `client.snapshots` / `.drives` / `.integrations` / `.detect` / `.accounts`
+
+- `snapshots.list() / create(vm_id, name=None) / clone(snapshot_id, *, name=None, environment_variables=None) / delete(snapshot_id)`
+- `drives.list() / create(name, size_gib, *, mount_path=None) / delete(id)`
+- `integrations.list() / create(**fields) / delete(id)`
+- `detect.public(repo_url, *, on_progress=None) / zip(zip_bytes, ...) / folder(path, ...)`
+- `accounts.current()` → `CurrentPrincipal(account, project, auth_type, api_key)`
+
+### System status
+
+Not a dedicated resource; use the generic request helper:
+
+```python
+from previews import SystemStatus
+status = SystemStatus.from_dict(client.request("GET", "/system/status"))
+print(status.caches["npm"].size_bytes)
+```
+
+## Errors
+
+Non-2xx responses raise `PreviewsApiError(status, code, message)` from the
+`{ error: { code, message } }` envelope (a non-JSON body yields code `UNKNOWN`).
+`wait_until_running` raises `PreviewsTimeoutError` on deadline. Missing
+credentials raise `PreviewsConfigError`.
+
+## Models
+
+Responses are frozen dataclasses with a tolerant `from_dict` (camelCase →
+snake_case, unknown keys ignored): `Preview` (alias `VM`), `RunCommandResult`,
+`VMSnapshot`, `DetectionResult`/`EnvVarHint`, `BandwidthSample`/`BandwidthResponse`,
+`Account`/`Project`/`ApiKeyRef`/`CurrentPrincipal`, `DatabaseIntegration`,
+`Drive`, `SystemStatus`/`CacheStat`, `WidgetToken`, `UploadResult`, `LogEvent`.
+The package ships `py.typed`.
+
+## Widget backend proxy
+
+The React widget UI is built separately. This SDK provides the backend piece.
+
+**Scoped token (recommended):** mint a short-lived `pwt_` token server-side and
+hand it to the browser, which then calls the platform directly.
+
+```python
+token = client.vms.mint_widget_token(vm_id, capabilities=["preview:read", "vm:run"])
+```
+
+**Backend proxy:** the browser calls *your* server; the proxy forwards only a
+whitelisted subset of operations to the platform using the `pvk_` key it holds —
+the key never reaches the browser.
+
+```python
+from previews import PreviewsClient
+from previews.proxy import PreviewsProxy, ProxyConfig, make_router  # or make_blueprint
+
+client = PreviewsClient()
+proxy = PreviewsProxy(ProxyConfig(
+    client=client,
+    allowed_origins=["https://app.example.com"],
+    allowed_vm_ids={"<vm-uuid>"},          # None = any VM in the project
+    # allow_ops defaults to WIDGET_SAFE_OPS = {"status","run","files","logs","mint_token"}
+))
+
+# FastAPI
+from fastapi import FastAPI
+app = FastAPI()
+app.include_router(make_router(proxy, prefix="/previews"))
+
+# Flask
+# from flask import Flask
+# app = Flask(__name__)
+# app.register_blueprint(make_blueprint(proxy, url_prefix="/previews"))
+```
+
+The proxy enforces the origin allowlist, the op whitelist (hard-capped to the
+widget-safe set), and the per-VM restriction; it never echoes the `pvk_` key.
+
+## License
+
+MIT

treinta_previews-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "treinta-previews"
+dynamic = ["version"]
+description = "Python SDK for the Propie / Previews VM-as-a-Service platform (Firecracker microVMs)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Treinta Previews", email = "carrizofg@gmail.com" }]
+keywords = ["previews", "propie", "firecracker", "vm", "microvm", "sdk"]
+dependencies = ["httpx>=0.27,<1"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://previews.amapola.treinta.ai"
+Repository = "https://github.com/justfedec/previews"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+flask = ["flask>=2.2"]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio",
+    "anyio",
+    "mypy",
+    "ruff",
+    "build",
+    "twine",
+]
+
+[tool.hatch.version]
+path = "src/previews/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/previews"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src",
+    "tests",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+# UP (pyupgrade) is intentionally not selected: the SDK targets Python 3.9, so
+# it uses typing.List/Dict/Optional rather than PEP 585/604 builtins.
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = true
+ignore_missing_imports = true

treinta_previews-0.1.0/scripts/smoke.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""End-to-end smoke test against a live Previews API.
+
+Exercises the full happy path:
+
+    accounts.current -> detect -> create -> wait_until_running -> run
+    -> logs -> upload_files -> mint_widget_token -> destroy
+
+Run it manually (it is NOT part of the offline pytest suite)::
+
+    export TREINTA_PREVIEWS_API_KEY=pvk_...
+    python scripts/smoke.py https://github.com/vercel/next.js
+
+This module must import and parse cleanly even without an API key.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from previews import PreviewsClient
+
+
+def main(repo_url: str) -> int:
+    with PreviewsClient() as client:
+        principal = client.accounts.current()
+        acct = principal.account.name if principal.account else "?"
+        print(f"[accounts] authenticated as account={acct} project={principal.project.slug if principal.project else '?'}")
+
+        print(f"[detect] {repo_url} ...")
+        detection = client.detect.public(repo_url, on_progress=lambda m: print(f"  .. {m}"))
+        print(f"[detect] stack={detection.stack} start={detection.start_command!r} port={detection.exposed_port}")
+
+        print("[create] launching VM ...")
+        vm = client.vms.create(
+            repo_url=detection.repo_url or repo_url,
+            stack=detection.stack,
+            branch=detection.branch or "main",
+            exposed_port=detection.exposed_port or 3000,
+            install_command=detection.install_command,
+            start_command=detection.start_command,
+        )
+        print(f"[create] id={vm.id} status={vm.status}")
+
+        try:
+            print("[wait] polling until running ...")
+            vm = client.vms.wait_until_running(
+                vm.id, on_status=lambda v: print(f"  .. status={v.status}")
+            )
+            print(f"[wait] running at {vm.url}")
+
+            result = client.vms.run(vm.id, "echo hello && uname -a")
+            print(f"[run] exit={result.exit_code} out={result.stdout.strip()!r}")
+
+            print("[logs] tailing (first buffered burst) ...")
+            for i, event in enumerate(client.vms.logs(vm.id, follow=False)):
+                print(f"  [{event.event}] {event.message}")
+                if i > 20:
+                    break
+
+            upload = client.vms.upload_files(
+                vm.id, {"smoke.txt": "written by scripts/smoke.py\n"}, base_dir="/app"
+            )
+            print(f"[files] wrote {upload.written} file(s): {upload.paths}")
+
+            token = client.vms.mint_widget_token(vm.id, capabilities=["preview:read"], ttl_seconds=300)
+            print(f"[widget] token={token.token[:12]}... expires={token.expires_at}")
+        finally:
+            destroyed = client.vms.destroy(vm.id)
+            print(f"[destroy] id={destroyed.id} status={destroyed.status}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("usage: python scripts/smoke.py <public-github-repo-url>", file=sys.stderr)
+        raise SystemExit(2)
+    raise SystemExit(main(sys.argv[1]))