新しいハーネスアダプターの作成

Apothem へのファーストパーティ組み込み、またはサードパーティパッケージとして 新しいハーネスアダプターを作成する際は、このランブックを使用してください。

前提条件Copy Anchor Link

• HarnessAdapter プロトコルへの理解
• 対象ハーネスの構成フォーマットの理解
• Python 3.10+

手順Copy Anchor Link

1. アダプターを実装するCopy Anchor Link

ハーネスアダプターの作成の例に従い、 対象ハーネス向けに HarnessAdapter を実装します。

アダプターがプレーンテキストのテンプレート（JSON でも YAML でもないファイル）を mode: write_text と ownership_class: operator-owned で書き込む場合、uninstall がそのファイルを削除するのは、それが Apothem の出荷したテンプレートの未編集のコピーである間だけです。 後のリリースでテンプレートが変更されたときは、同じ変更の中で、以前のテキストの SHA-256 ダイジェストを そのマニフェストエントリーの earlier_digests リストに追加してください。そうしないと、uninstall は 以前のリリースが書き込んだ未編集のコピーをすべてその場に残します。ダイジェストは、最新のリリースタグにおけるテキストから git show <tag>:<template path> | sha256sum で取得します。テンプレートには ${...} のパストークンを含めてはなりません。出荷されたテンプレートが考慮されていない場合、 tests/unit/test_template_digests.py は失敗します。

2. ドキュメントページを書くCopy Anchor Link

site/content/docs/harnesses/<slug>.mdx を作成し、次の内容を扱います。

• インストールフロー
• プロファイルからネイティブ構成へのマッピング
• 互換性に関する注意点
• 検証レシピ
• 更新・アンインストールレシピ
• コンフォーミティゲートの面
• トラブルシューティング表
• 構成つまみの表

3. テストを書くCopy Anchor Link

tests/packaging/test_<slug>_adapter.py
tests/unit/test_<slug>_adapter.py

最低限のテストカバレッジ:

• test_install_creates_expected_files
• test_verify_passes_after_install
• test_uninstall_removes_files

4. ローカルで検証するCopy Anchor Link

apothem install --harness <slug>
apothem verify --harness <slug>
python -m apothem.conformity.gate --all .

5. プルリクエストを提出するCopy Anchor Link

次の内容を含む PR を作成します。

• アダプターの実装
• site/content/docs/harnesses/<slug>.mdx のドキュメントページ
• テスト
• pyproject.toml でのエントリーポイント登録、src/apothem/lib/harness_registry_data.py の HARNESS_REGISTRY のエントリー（そこで SUPPORTED_HARNESS_COUNT を更新する）、および src/apothem/schemas/profile.schema.json の harnessId 列挙への ID の追加
• 変更履歴のエントリー