stdb-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{stdb_cli-0.1.0 → stdb_cli-0.1.1}/.gitignore

@@ -12,6 +12,8 @@ build/
 # uv / venv
 .venv/
 .uv/
+# stdb-cli is a published library — its lock file is not used by consumers or CI
+packages/cli/uv.lock
 
 # Environment
 .env
@@ -30,3 +32,5 @@ htmlcov/
 .vscode/
 .idea/
 *.iml
+
+.superpowers/

{stdb_cli-0.1.0 → stdb_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stdb-cli
-Version: 0.1.0
+Version: 0.1.1
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: python-dotenv>=1.2.2

stdb_cli-0.1.1/README.md

@@ -0,0 +1,124 @@
+# stdb-cli
+
+Command-line client for the STDB Service. Authenticates with an API key from the [STDB Portal](https://stdb-portal.csltaipeitech.com).
+
+## Install
+
+```bash
+pip install stdb-cli
+export STDB_API_KEY=<your-api-key>
+```
+
+## Usage
+
+```bash
+stdb search-location "大安區"
+stdb search-dataset "台北租屋坪數"
+stdb retrieve --cf demographics --cq population --res 8 --ts 2023-12-31 --location-id 12345
+```
+
+Run `stdb --help` for the full command list.
+
+## Local Development
+
+```bash
+cd packages/cli
+uv sync
+uv run stdb --help
+```
+
+To test a local build:
+
+```bash
+uv build
+pip install dist/stdb_cli-<version>-py3-none-any.whl
+```
+
+## Releasing to PyPI
+
+Releases are fully driven by Git tags. **You never run `uv publish` manually** — CI does it.
+
+### Step-by-step
+
+1. **Bump the version** in `pyproject.toml`:
+
+   ```toml
+   [project]
+   name = "stdb-cli"
+   version = "0.1.1"   # ← bump here
+   ```
+
+   Follow [semver](https://semver.org): patch for fixes, minor for features, major for breaking changes.
+
+2. **Commit and push** the version bump:
+
+   ```bash
+   git add packages/cli/pyproject.toml
+   git commit -m "chore(cli): bump to 0.1.1"
+   git push
+   ```
+
+3. **Tag and push the tag** (tag must match the version, prefixed with `cli-v`):
+
+   ```bash
+   git tag cli-v0.1.1
+   git push origin cli-v0.1.1
+   ```
+
+4. **Watch the workflow** at GitHub → Actions → *Publish CLI to PyPI*. Once green, install with:
+
+   ```bash
+   pip install -U stdb-cli
+   ```
+
+### Why this order matters
+
+The workflow verifies that the tag suffix (`0.1.1`) matches `pyproject.toml`'s `version` field. If you tag before bumping, CI fails on the first step — by design, to prevent accidentally publishing the wrong version. Always bump → commit → tag.
+
+PyPI also does not allow overwriting an existing version. If a release fails partway through, bump to the next patch (`0.1.2`) rather than trying to re-push `0.1.1`.
+
+## CI/CD Design
+
+Workflow file: [`.github/workflows/deploy-cli.yml`](../../.github/workflows/deploy-cli.yml)
+
+### Trigger
+
+```yaml
+on:
+  push:
+    tags:
+      - 'cli-v*'
+```
+
+Only tags matching `cli-v*` (e.g. `cli-v0.1.1`, `cli-v1.0.0`) trigger publishing. Pushes to branches, other tag patterns, and PRs do nothing — keeping the publish path narrow and intentional.
+
+### Steps
+
+1. **Checkout** the tagged commit.
+2. **Install uv** (via `astral-sh/setup-uv@v5`) and Python 3.12.
+3. **Verify tag vs. version**: extract the version from the tag (`cli-v0.1.1` → `0.1.1`), parse `pyproject.toml`'s `[project].version`, fail if they differ.
+4. **Build** the sdist and wheel with `uv build` into `dist/`.
+5. **Publish** to PyPI using `pypa/gh-action-pypi-publish@release/v1`.
+
+### Authentication: Trusted Publishing (OIDC)
+
+The workflow uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no long-lived API token. Instead:
+
+- The job declares `permissions: id-token: write`, letting GitHub Actions mint a short-lived OIDC token.
+- PyPI verifies the token's claims (`repo = CityScience-TaipeiTech/STDB_mcp`, `workflow = deploy-cli.yml`, `environment = pypi`) against a publisher registered on the PyPI project page.
+- If they match, PyPI accepts the upload. If anything is off (wrong repo, wrong workflow filename, wrong environment), upload is rejected.
+
+This means there is no PyPI secret stored in this repository. A stolen API token can no longer be used to publish malicious versions — only a workflow run from this exact repo + workflow + environment can publish.
+
+### One-Time Setup (already done for this project)
+
+For reference, the trusted publisher is configured at [pypi.org](https://pypi.org) → `stdb-cli` → Manage → Publishing:
+
+| Field           | Value                          |
+| --------------- | ------------------------------ |
+| Owner           | `CityScience-TaipeiTech`       |
+| Repository name | `STDB_mcp`                     |
+| Workflow name   | `deploy-cli.yml`               |
+| Environment    | `pypi`                         |
+
+The matching `pypi` environment exists at GitHub → Settings → Environments.

{stdb_cli-0.1.0 → stdb_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stdb-cli"
-version = "0.1.0"
+version = "0.1.1"
 requires-python = ">=3.12"
 dependencies = [
     "httpx>=0.28.0",

{stdb_cli-0.1.0 → stdb_cli-0.1.1}/src/stdb_cli/client.py

@@ -2,13 +2,17 @@ from __future__ import annotations
 import os
 import httpx
 
-STDB_ENDPOINT = os.getenv("STDB_ENDPOINT", "https://stdb-mcp.azurecontainerapps.io")
+STDB_ENDPOINT = os.getenv("STDB_ENDPOINT", "https://stdb.csltaipeitech.com")
 STDB_API_KEY = os.getenv("STDB_API_KEY", "")
 
 
 def get_client() -> httpx.Client:
     if not STDB_API_KEY:
-        raise SystemExit("STDB_API_KEY environment variable is not set.")
+        raise SystemExit(
+            "STDB_API_KEY environment variable is not set.\n"
+            "Get one at https://stdb-portal.csltaipeitech.com and run:\n"
+            "  export STDB_API_KEY=<your-key>"
+        )
     return httpx.Client(
         base_url=f"{STDB_ENDPOINT}/v1",
         headers={"Authorization": f"Bearer {STDB_API_KEY}"},