permix

Permix

Permix の権限に関わる作業（定義、setup／check、SSR のハイドレーション、UI アダプター、サーバーミドルウェア、NestJS ガード、v3→v4 の移行）では、このスキルを使用してください。

スナップショット：[email protected]（2026-10-01 に検証済み）。インストール済みのバージョンが異なる場合は、source-map.md を参照して更新してください。

ワークフロー

1. ローカルの Permix の構成を確認します。
   • パッケージのバージョン（[email protected] を推奨。現在の安定版スナップショットは 4.3.0）。
   • インポートパス：permix（コア）とサブパス（permix/react、permix/next、permix/nest、permix/tanstack-start など）。
   • 定義の形式：アクションタプル／{ name, type, required? } と、従来の v3 の { action, dataType }。
   • 強制適用の実行場所（サーバーミドルウェア／Nest の @Check とクライアント UX）および SSR の dehydrate／hydrate の使用有無。
2. 日常的な使い方については、まず usage-guide.md に従ってください。
3. バージョンに差異がある場合や、移行／SSR／インテグレーションに特化したタスクでは、ドキュメントを更新してください。source-map.md から始めてください。
4. 詳細情報の参照先：
   • コア API、ルール、check、テンプレート、ReBAC、エラー：core-api.md。
   • React／Vue／Solid／Svelte、Next、TanStack Start、ハイドレーション：frameworks-ssr.md。
   • Express／Hono／Elysia／Fastify／Node／server／tRPC／oRPC／Nest／Drizzle／Effect：server-integrations.md。
   • v3→v4 の破壊的変更：migration-v4.md。
5. Permix v4 の API（ドットパス、アクションタプル）を優先してください。クライアント側のチェックは UX のみを目的とし、サーバー側で強制適用してください。
6. 型チェックに加え、setup／check に焦点を当てたテストで検証してください（サーバーと統合する場合は、ミドルウェアの 403 と Nest の ForbiddenException の経路も確認してください）。

コアの判断基準

• フロー：createPermix<Definition>() → setup(rules) → check('entity.action'[, data])。
• 定義はアクションリスト（文字列、または { name, type?, required? }）で、必要に応じてツリー状にネストできます。
• ルールは真偽値、または (data?) => boolean クロージャーです（setup 時点のアクターをキャプチャします）。
• check は boolean を返します。AND／OR にはコールバックを使用し、集約には '~all'／'~any'（または 'post.~all'）を使用します。
• v4 では checkAsync は削除されています。await isReadyAsync() の後に check() を呼び出してください。
• ルールを設定する前に check／dehydrate を呼び出すと、false ではなく PermixNotReadyError がスローされます。
• 無効なパスでは PermixRuleNotDefinedError がスローされます。
• template(...) は関数を返します。呼び出してください：permix.setup(admin())。
• SSR：dehydrate() → JSON の真偽値（関数は false になります）→ クライアント側で hydrate → 関数ルールを使う場合は必ず再度 setup() を呼び出してください。hydrate だけでは isReady は設定されません。
• サーバー：インテグレーションのミドルウェア／Nest の guard／Next の cache() を使い、リクエストごとにインスタンスを用意することを推奨します。複数のリクエスト間で変更可能なコアのシングルトンを共有しないでください。
• TanStack Start：setupMiddleware を使用します（または、コールバックがサーバー専用コードをインポートする場合は、createMiddleware().server(...) 内で createSetupHandler を使用します）。ルーターの beforeLoad／loader はルーターコンテキスト上の別個のコアインスタンスを使います（UX のみ）。
• NestJS：permix/nest を使用します。guard() がリクエストごとのルールを設定し、@Check が強制適用します（フェイルクローズ）。HTTP のみ（Express／Fastify アダプター）。
• セキュリティ：サーバー側での強制適用は必須です。UI を非表示にする用途でのみ、クライアント側のチェックを使用してください。
• エンジン：パッケージが宣言する要件は node: >=22 です。オプションのピア依存関係は、インポートするアダプターに必要なものだけです。

検証

リポジトリが提供するコマンドを優先してください。Permix に関する重要な作業では、該当する項目を確認してください。

• 型チェックのパス（$inferPath）、required: true のデータ引数、共有の ValidateDefinition／Rules。
• 単体テスト：許可／拒否、データの有無によるエンティティデータルール、~all／~any、コールバックの合成、未準備／パス不足のエラー。
• SSR：デハイドレートされたスナップショットの形式、クライアントでのハイドレートと再度の setup、UI での isReady による制御。
• サーバー：setupMiddleware の後に checkMiddleware を実行し、200 と 403／onForbidden を検証します。Nest：APP_GUARD と @Check → 201 と 403、ガードがない場合 → PermixNotFoundError。
• TanStack Start：強制にはサーバー関数の checkMiddleware／getOrThrow(context) を使用します。beforeLoad でのチェックだけでは不十分です。
• 移行：check('entity', 'action')、checkAsync、Better Auth プラグイン、entity と action の UI プロパティが残っていないこと。

実行したチェック、実行しなかったチェック、および未解決のバージョンに関する前提を報告してください。