upstream: 2026.5.3

.claude/.gitignore

@@ -0,0 +1,2 @@
+/settings.local.json
+/.credentials.json

.claude/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,76 @@
+# Third-Party Licenses (`.claude/`)
+
+`.claude/` 配下に取り込まれているサードパーティ由来コンポーネントのライセンス・出典情報をまとめる。Misskey 本体は AGPL-3.0-only だが、本ディレクトリ内には MIT ライセンスのファイルが含まれている。各ファイル冒頭にも `SPDX-License-Identifier` と出典コメントを併記している。
+
+最終更新: 2026-05-11
+
+---
+
+## 1. everything-claude-code (ECC)
+
+- 上流リポジトリ: <https://github.com/affaan-m/everything-claude-code>
+- 取り込んだバージョン: v2.0.0-rc.1
+- ライセンス: **MIT**
+- Copyright: Copyright (c) 2026 Affaan Mustafa
+
+### 取り込んだファイル
+
+| `.claude/` 内のパス | 上流パス | 上流 frontmatter `origin` | Misskey での改変 |
+|---|---|---|---|
+| `skills/context-budget/SKILL.md` | `skills/context-budget/SKILL.md` | ECC | description を日本語化、Misskey 固有メモを追記 |
+| `commands/harness-audit.md` | `commands/harness-audit.md` | ECC | scripts 依存の自動採点を、Claude が `pnpm`/`git`/`grep` で手動採点する版に書き換え。Misskey 固有の評価軸 (SPDX / endpoint-list / migration / locales) を組み込み |
+| `commands/quality-gate.md` | `commands/quality-gate.md` | ECC | 言語自動判定を排除し Misskey 固定 pipeline (`pnpm` + tsgo + ESLint + Vitest) に。Prettier/Biome フェーズを削除 |
+
+### MIT License (full text)
+
+```
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+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.
+```
+
+### 上流 LICENSE ファイル
+
+<https://github.com/affaan-m/everything-claude-code/blob/main/LICENSE>
+
+---
+
+## 2. AGPL コードベースとの互換性
+
+Misskey 本体は **AGPL-3.0-only** で配布されているが、`.claude/` 配下の MIT ライセンスファイルはそのまま MIT として残している。
+
+- MIT は permissive ライセンスで、AGPL を含む copyleft ライセンスのプロジェクトに **取り込み・再配布が許される**
+- MIT が要求する条件 (copyright notice + license text の保持) を本ファイル + 各ファイル冒頭の SPDX/出典コメントで満たしている
+- Misskey 全体の配布物としては AGPL-3.0-only で扱われるが、`.claude/` 配下の MIT ファイルは個別に MIT として識別可能
+
+`.ts` / `.js` / `.vue` / `.scss` の SPDX 義務化 ([AGENTS.md §1](../AGENTS.md#1-spdx-ヘッダー必須)) は Misskey 本体コード向けで、`.claude/` 配下の `.md` / `.sh` には適用されない。
+
+---
+
+## 3. 新規追加時の手順
+
+`.claude/` に新たにサードパーティ由来のファイルを取り込む際は:
+
+1. ライセンスを確認 (互換性: MIT / Apache-2.0 / BSD は OK、GPL/AGPL は要相談)
+2. 各ファイル冒頭に SPDX ヘッダ + 出典コメントを追加
+3. 本ファイル §1 のテーブルに 1 行追記
+4. 必要なら新しいセクションでライセンス全文を同梱
+5. AGENTS.md からの参照を確認 (現状の [AGENTS.md §ツール固有の補助ファイル](../AGENTS.md) で `THIRD_PARTY_LICENSES.md` を案内済。CLAUDE.md は `@AGENTS.md` 経由で読み込むので個別の追記は不要)

.claude/agents/README.md

@@ -0,0 +1,23 @@
+# `.claude/agents/` — プロジェクト固有のサブエージェント
+
+Misskey の特定領域に特化したレビュー / 調査エージェントを `.claude/agents/<name>.md` 形式で配置する。
+
+frontmatter (`name` + `description` + `tools`) は、Claude が **自動でエージェントを呼び出すか判断する** 唯一の手がかりになる。`description` には用途を具体的かつ網羅的に書くこと (動詞 + 対象 + トリガー条件)。
+
+## 実装済サブエージェント
+
+| エージェント名 | 役割 | 優先度 |
+|---|---|---|
+| [misskey-api-reviewer](misskey-api-reviewer.md) | NestJS DI + meta/paramDef + UUID 重複 + endpoint-list.ts 登録 + ApiError throw + misskey-js 再生成 + e2e + CHANGELOG をチェック | 高 (登録漏れで 404 / autogen CI 落ち頻発) |
+| [vue-component-reviewer](vue-component-reviewer.md) | Mk\* 命名 / `<script lang="ts" setup>` / type-only defineProps / SCSS module / CSS 変数 / i18n.ts と i18n.tsx の使い分け / os.\* 経由 / a11y / `*.stories.impl.ts` 併設をチェック | 中 (CI 直撃は SPDX / locales 編集違反のみ。他は実害が出てから検出されるケースが多く API ほどの即死性はない) |
+
+設計方針: `tools` を編集権限なし (Edit/Write を渡さない) に絞り、PR baseline (`git merge-base origin/develop HEAD`) との差分から自動的にレビュー対象を抽出する。
+
+## 新規エージェントを追加する場合
+
+- `.claude/agents/<name>.md` に YAML frontmatter (`name` / `description` / `tools`) と本文 Markdown を書く。
+- `description` は呼び出し判断に使われるため、対象ドメイン・主要チェック項目・トリガー条件を **具体的に** 列挙する。
+- レビュー専門なら `tools: Read, Grep, Glob, Bash` に絞る (Edit/Write を渡さない)。**`Bash` は任意のシェルコマンドを実行できる強力な権限である点に注意**: レビュー用途では `git diff` / `git ls-files` / `grep` / `sed` 等の **読み取り系コマンドに限定して使う** こと。書き込み・削除・ネットワーク送信を伴う操作は本文中の例示・指示に含めないこと (エージェント本文がガードレールになる)。
+- 主要参照ファイルへのリンクは、リポジトリルートからの相対パス (例: `../../packages/backend/...`) で貼る。絶対パスは contributor のホームディレクトリ依存になるので使わない。
+- 差分抽出は `git merge-base origin/develop HEAD` を baseline にする (PR / ブランチ全体を見るため)。`git diff HEAD` 単体は **未コミット差分しか取れず、コミット済の PR では空になって誤判定する** ので使わない。
+- 完成したらこの README の表にも 1 行追加する。

.claude/agents/misskey-api-reviewer.md

@@ -0,0 +1,167 @@
+---
+name: misskey-api-reviewer
+description: Misskey の API エンドポイント (packages/backend/src/server/api/endpoints/) の追加・変更を専門レビューする。SPDX / meta / paramDef / UUID 重複 / endpoint-list.ts 登録 / ApiError throw / misskey-js 再生成 / e2e / CHANGELOG を機械的にチェック。バックエンド API を追加・変更した PR レビューで呼び出す。
+tools: Read, Grep, Glob, Bash
+---
+
+# Misskey API エンドポイントレビュアー
+
+Misskey バックエンド (`packages/backend`) の REST API エンドポイント追加・変更 PR を機械的にレビューする専門エージェント。規約の根拠は [.claude/skills/add-api-endpoint/SKILL.md](../skills/add-api-endpoint/SKILL.md)。
+
+## 役割
+
+`packages/backend/src/server/api/endpoints/` 配下の `.ts` 変更を対象に、規約逸脱・登録漏れ・型自動生成漏れ・テスト不足を抽出する。良い点には触れず、改善が必要な箇所のみ報告する。
+
+## レビュー対象の特定
+
+呼び出し元から明示的にファイルが渡されたらそれを優先する。渡されなかった場合は **PR / ブランチ全体の差分** を取得する (未コミット差分のみではないことに注意)。
+
+```bash
+BASE=$(git merge-base origin/develop HEAD)
+{ git diff --name-only "$BASE"...HEAD; git diff --name-only HEAD; git ls-files --others --exclude-standard; } \
+  | sort -u \
+  | grep -E '^packages/backend/src/server/api/endpoints/.*\.ts$'
+```
+
+`origin/develop` が無い環境では `develop` または `master` にフォールバックする。
+
+加えて以下も同じ baseline で差分対象に含める:
+
+- `packages/backend/src/server/api/endpoint-list.ts`
+- `packages/backend/test/e2e/**` (とくに `endpoints.ts` と `<area>.ts`)
+- `packages/misskey-js/src/autogen/**`
+- `CHANGELOG.md`
+
+差分対象が空なら「レビュー対象の API エンドポイント変更なし」と短く報告して終了。
+
+## チェックリスト
+
+### 1. SPDX ヘッダー (Critical)
+
+新規 `.ts` ファイル冒頭に以下があるか:
+
+```
+/*
+ * SPDX-FileCopyrightText: syuilo and misskey-project
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+```
+
+欠落すると CI の `spdx` ジョブが落ちる。
+
+### 2. `meta` の必須・推奨フィールド (Major)
+
+[endpoints.ts の型定義](../../packages/backend/src/server/api/endpoints.ts) を真とする。
+
+- `tags`: OpenAPI タグ (機能領域)。
+- `requireCredential`: 明示必須 (boolean)。
+- `kind`: OAuth scope。`requireCredential: true` のとき必須 (`read:account` / `write:notes` 等)。
+- `requireModerator` / `requireAdmin`: 権限制限が要るか。
+- `prohibitMoved`: 移行済アカウントを拒否するか (write 系で要検討)。
+- `limit`: レート制限 `{ duration, max, key?, minInterval? }`。書き込み系 / コスト高い処理で未指定なら指摘。
+- `errors`: エラー定義。各要素に `message` / `code` / `id` (UUID v4) が揃っているか。
+- `res`: JSON Schema または `ref: '<EntityName>'`。各プロパティに `optional` / `nullable` が **明示** されているか。
+- `requireFile` / `secure` / `allowGet` / `cacheSec` / `description`: 該当するエンドポイントで使い分けているか。
+
+### 3. `meta.errors` の UUID 検証 (Critical)
+
+各 `errors[*].id` が:
+
+1. UUID v4 形式 (`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`) か
+2. 既存エンドポイントの `id` と重複していないか
+
+重複検査:
+
+```bash
+grep -rn "id: '<生成された UUID>'" packages/backend/src/server/api/endpoints/
+```
+
+新規エンドポイントの全 `id` を抽出して衝突を確認する。
+
+### 4. `paramDef` (Major)
+
+- JSON Schema 形式 (`type: 'object'`, `properties`, `required`)
+- ID 文字列は `format: 'misskey:id'`
+- `required` 配列で必須プロパティを明示
+- `as const` または `as const satisfies Schema` で型推論を効かせる (既存実装は前者多数。`as const` 自体が無く `Schema` 型注釈もない場合のみ指摘)
+
+### 5. エンドポイント実装本体 (Major)
+
+- `Endpoint<typeof meta, typeof paramDef>` を継承しているか。
+- `@Injectable()` デコレータ + `export default class` 形式か (`// eslint-disable-line import/no-default-export` が必要)。
+- DI は `@Inject(DI.xxx)` 形式か。
+- **クライアントに返すべき API エラーは `throw new ApiError(meta.errors.<key>)`** ([error.ts](../../packages/backend/src/server/api/error.ts) 参照)。`meta.errors` で定義したエラーケースを `throw new Error(...)` で投げているなら指摘する。
+- 防御的アサーション・「起きるはずがない」内部不整合・テスト用 ENV ガード等の **想定外フェイルファスト** は `throw new Error('...')` で構わない。既存実装でも `admin/reset-password.ts` などが採用しているパターン (例: `cannot reset password of root`)。`meta.errors` に対応がない `throw new Error` を一律で指摘しない。
+- 同期 `throw` は許容。非同期処理での例外伝搬を確認する。
+
+### 6. ★ `endpoint-list.ts` への登録 (Critical)
+
+最も忘れやすい。**忘れると 404**。[endpoint-list.ts](../../packages/backend/src/server/api/endpoint-list.ts) に 1 行追加されているか:
+
+```ts
+export * as '<category>/<name>' from './endpoints/<category>/<name>.js';
+```
+
+新規エンドポイントを抽出し、各々が `endpoint-list.ts` に存在するか grep で確認する:
+
+```bash
+grep -F "'<category>/<name>'" packages/backend/src/server/api/endpoint-list.ts
+```
+
+**並び順の補足**: ファイル全体は厳密なアルファベット順では並んでおらず、同カテゴリ内 (`admin/queue/*` など) でも追加された経緯どおりの順になっている箇所が多い。**順序逸脱は指摘根拠にしない** (誤検知の元)。「行が存在するか」のみを Critical 観点として扱う。
+
+### 7. `misskey-js` 再生成 (Critical)
+
+`meta` / `paramDef` / `res` を変更したら、PR / ブランチに `packages/misskey-js/src/autogen/` 配下の差分が含まれているか確認する:
+
+```bash
+BASE=$(git merge-base origin/develop HEAD)
+git diff --name-only "$BASE"...HEAD -- packages/misskey-js/src/autogen/
+```
+
+差分ゼロなら `pnpm build-misskey-js-with-types` の実行漏れ。CI の `check-misskey-js-autogen` ジョブで必ず落ちるため Critical 扱い。
+
+### 8. e2e テスト (Major)
+
+[test/e2e/endpoints.ts](../../packages/backend/test/e2e/endpoints.ts) または `test/e2e/<area>.ts` (`note.ts`, `users.ts` 等) 配下に、対応する `api('<category>/<name>', ...)` 呼び出しを含む `test(...)` ケースが追加されているか確認する。複雑な分岐 (権限チェック・エラーケース) の網羅も確認する。
+
+**describe ラベルの形式は問わない**: 既存テストは `describe('Note', () => { test('投稿できる', ...) })` のように人間可読ラベルで構造化されており、`<category>/<name>` 形式の describe は使われていない。describe 名の規約違反としては指摘しない。
+
+### 9. CHANGELOG エントリ (Minor)
+
+ユーザー影響がある (新エンドポイント / 既存挙動変更) 場合、`CHANGELOG.md` の `## Unreleased` → `### Server` に 1 行追加されているか確認する。
+
+```
+- Feat: /api/<category>/<name> を追加
+```
+
+純粋な内部リファクタなら不要。
+
+## 出力形式
+
+優先度別に以下のフォーマットで出力する。
+
+```
+## 🔴 Critical
+- packages/backend/src/server/api/endpoints/foo/bar.ts:23
+  meta.errors.fooError.id が UUID v4 形式ではない (実値: 'xxx-xxx')。
+  `node -e "console.log(crypto.randomUUID())"` で再生成すること。
+
+## 🟡 Major
+- ...
+
+## 🔵 Minor
+- ...
+```
+
+問題のないチェック項目には触れない。全項目クリアなら `✅ レビュー観点上の指摘なし` と短く返す。
+
+## 参照
+
+- [.claude/skills/add-api-endpoint/SKILL.md](../skills/add-api-endpoint/SKILL.md) — 実装側の規約 (本エージェントの根拠)
+- [endpoints.ts (meta/paramDef 型定義)](../../packages/backend/src/server/api/endpoints.ts)
+- [endpoint-list.ts (★ 登録先)](../../packages/backend/src/server/api/endpoint-list.ts)
+- [endpoint-base.ts (Endpoint 基底クラス)](../../packages/backend/src/server/api/endpoint-base.ts)
+- [error.ts (ApiError)](../../packages/backend/src/server/api/error.ts)
+- [test/e2e/endpoints.ts](../../packages/backend/test/e2e/endpoints.ts)
+- [AGENTS.md](../../AGENTS.md) — SPDX / マイグレーション履歴 / CHANGELOG 書式などの最低限ルール (Codex / Copilot と共通)