Metadata-Version: 2.4
Name: wonderfish-cp-sdk
Version: 12.0.2
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: azure-identity<2,>=1.25.3
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: pyjwt[crypto]<3,>=2.15.0
Provides-Extra: dev
Requires-Dist: build==1.6.1; extra == "dev"
Requires-Dist: colorama==0.4.6; extra == "dev"
Requires-Dist: jeepney==0.9.0; sys_platform == "linux" and extra == "dev"
Requires-Dist: jsonschema==4.26.0; extra == "dev"
Requires-Dist: pip-audit==2.10.1; extra == "dev"
Requires-Dist: python-multipart<1,>=0.0.20; extra == "dev"
Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
Requires-Dist: pywin32-ctypes==0.2.3; extra == "dev"
Requires-Dist: ruff==0.16.7; extra == "dev"
Requires-Dist: setuptools==84.0.0; extra == "dev"
Requires-Dist: secretstorage==3.5.0; sys_platform == "linux" and extra == "dev"
Requires-Dist: twine==7.0.0; extra == "dev"
Dynamic: license-file

# wonderfish-cp-sdk

Product ServiceからMVP Control Planeを呼び出すPython SDK。型付きclient、Managed Identity認証、Catalog cache、顧客・Product Service間Token検証を提供する。公開仕様は[SDK仕様書](<docs/DetailDesign/Product Service SDK仕様書.md>)、HTTP契約は[contracts](contracts/README.md)を参照する。

## 取得

Python 3.12以上で、正式公開後にPublic PyPIのversionを固定して導入する。

```sh
pip install wonderfish-cp-sdk==12.0.2
```

接続先のControl Planeは、`contracts/internal.openapi.json`と同じHTTP契約を提供すること。クラウド環境は`dev`・`prod`とし、管理下ResourceとバージョンなしAPIパスを使う。

公開前のlocal検証ではこのcommitからwheelをビルドし、そのwheelを検証環境へ導入する。正式配置では公開済みwheelを使う。

## ローカル検証

```sh
python -m pip install --require-hashes -r requirements-dev.lock
python -m pip install --require-hashes -r deployment/sample/requirements.lock
python -m ruff check src tests deployment .github/scripts
python -m compileall -q src tests deployment .github/scripts
python -m pytest
python -m pip_audit -r requirements-dev.lock
python -m pip_audit -r deployment/sample/requirements.lock
node --check deployment/sample/assets/ui.mjs
node --test tests/test_sample_*.mjs
python deployment/sample/download_msal.py
python -c "import pathlib, shutil; [shutil.rmtree(p, ignore_errors=True) for p in [pathlib.Path('build'), pathlib.Path('dist'), *pathlib.Path('src').glob('*.egg-info')]]"
python -m build --wheel --no-isolation
python -m twine check --strict dist/*.whl
python .github/scripts/validate_wheel.py dist 12.0.2
python -m pip install --force-reinstall --no-deps dist/*.whl
python deployment/sample/smoke.py
```

ブラウザー処理の検証にはNode.js 22.23.2を使う。MSAL取得はビルド時の固定hash検査であり、pytestとNodeテストにはネットワークを使わない。

pytestとNodeテスト、smokeはネットワーク不要の開発検証。依存導入・監査・MSAL取得にはネットワークを使う。実CPとのHTTP・画面の結合試験は[サンプル開発手順](<docs/サンプルアプリ開発手順書.md>)と[試験項目書](<docs/サンプルアプリ結合試験項目書.md>)に従い、localの実CPとDevの実Managed Identityの結果を別に記録する。sample Docker imageのlock同期はDockerfileが指定する固定Python imageで`pip-compile`して確認する。

開発用lockはsample Dockerfileの固定Python 3.12.14イメージと`pip-tools==7.6.1`で生成する。WindowsとLinuxで必要な条件付き依存をdev extraに明示し、同じlockを両OSで使う。lockは手で編集しない。特定の依存を更新するときは対応する`pip-compile`に`--upgrade-package <name>`を付ける。

```sh
image="$(awk '/^FROM /{print $2}' deployment/sample/Dockerfile)"
docker run --rm --volume "${PWD}:/work" --workdir /work "$image" \
  sh -c 'python -m pip install --quiet pip-tools==7.6.1 && pip-compile --quiet --allow-unsafe --extra=dev --generate-hashes --output-file=requirements-dev.lock pyproject.toml && cd deployment/sample && pip-compile --quiet --generate-hashes --output-file=requirements.lock requirements.in'
```

再生成後は、次のコマンドでWindows/Linux向けの全wheelのhashと、Python 3.12.14で有効な依存関係を検査する。`pip download`のplatform指定だけでは依存条件が実行ホストで評価されるため、wheel内のメタデータも対象OSの条件で検証する。これは対象OS上での動作試験とは区別する。

```sh
wheel_root="$(mktemp -d /tmp/$(date +%Y%m%d%H%M%S)_sdk-wheels.XXXXXX)"
python -m pip download --only-binary=:all: --require-hashes -r requirements-dev.lock \
  --python-version 3.12 --implementation cp --abi cp312 --platform win_amd64 --dest "$wheel_root/windows"
python -m pip download --only-binary=:all: --require-hashes -r requirements-dev.lock \
  --python-version 3.12 --implementation cp --abi cp312 --platform manylinux_2_28_x86_64 \
  --platform manylinux_2_17_x86_64 --platform manylinux2014_x86_64 --dest "$wheel_root/linux"
python .github/scripts/validate_dev_lock.py windows "$wheel_root/windows"
python .github/scripts/validate_dev_lock.py linux "$wheel_root/linux"
```

## PyPIへの公開

`pyproject.toml` の version を未公開の正式Semantic Versionに更新し、ローカル検証後に `main → release` のPRを作成する。必須チェック `sdk`・`release-ready` の成功後にマージすると、wheelのビルド・検証、PyPIへの公開、`v<version>` tagの付与を順に実行する。公開workflowはreleaseへのpush時に、対象commitが同一リポジトリのマージ済みmain→release PRのmerge commitであることをGitHub APIで検証する。mainへのpush・PRでは公開しない。

認証はPyPIのTrusted Publisherを使用する。登録先はowner `HappyHackInc`、repository `hh-wonderfish-ai-sdk`、workflow `publish-pypi.yml`、Environment `pypi` とし、GitHub側の `pypi` Environmentは `release` ブランチだけを許可する。公開済みversionとtagは変更せず、修正には新しいversionを使う。

## 構成

| 場所 | 用途 |
| --- | --- |
| `src/wonderfish_cp` | 公開SDK・認証・HTTP境界 |
| `src/wonderfish_cp/external` | 受信Tokenと実行呼出元の検証 |
| `tests` | ネットワーク不要の契約・単体テスト |
| `contracts` | CP OpenAPIの写し |
| `docs` | SDK仕様と検証用sampleの仕様 |
| `docs/DesignSystem` | CPとProduct Service共通の画面デザイン（トークン・部品・レイアウト）。配布物に含めない |
| `deployment/sample` | 単一プロセスの疎通確認用Product Service。配布物に含めない |

SDKはApache License 2.0で提供する。脆弱性・秘密情報は公開Issueへ記載せず`support@happyhack.co.jp`へ連絡する。
