KrabiClaw

KrabiClaw

KrabiClaw は、レストラン、体験事業者、法律事務所、宿泊施設のホスト向けに、ウェブサイト、予約、決済、メッセージングを提供します。ダッシュボード、または ChatGPT や Claude から単一の MCP サービスを通じて管理できます。宿泊施設には、住宅、宿泊可能日と料金、宿泊の直接予約、ゲストとのメッセージングが含まれます。

AGPL-3.0 の下でオープンソースとして公開されています。

• バグの報告や機能のリクエスト： issue を作成してください。 ユーザーに代わって issue を作成するアシスタントは、フォームに入力済みの内容を設定できます。フィールド ID については .github/ISSUE_TEMPLATE を参照してください。
• アカウント、請求、または非公開データ： krabiclaw.com/help。
• セキュリティ： SECURITY.md。
• コントリビューション： CONTRIBUTING.md。

Nuxt 5 nightly + Nitro 3 + Cloudflare Workers + D1。

パッケージマネージャーは yarn のみです。 npm または pnpm は使用しないでください。

---

スクリプト

コマンド	機能
yarn dev	HMR とローカルでエミュレートされた Cloudflare バインディングを備えた Nuxt 開発サーバーを http://localhost:3000 で起動します。
yarn local:setup	ローカルセットアップの唯一のエントリーポイントです。D1 をマイグレーションし、フィクスチャを更新し、ローカル開発者アカウントを作成して、結果を検証します。
yarn dev:worker	Wrangler を使って本番環境に近い Worker をビルドし、http://localhost:3000 でローカル実行します。
yarn dev:worker:start	既存の .output Worker ビルドを再ビルドせずにローカル実行します。
yarn build	本番ビルド → .output/
yarn db:generate	server/db/schema.ts から新しい migrations/*.sql ファイルを生成します。
yarn drizzle:check	server/db/schema.ts が実際の D1 スキーマとずれていないことを検証します。
yarn stripe:listen	Stripe のウェブフックを localhost に転送します（ローカル開発専用）。
yarn canary:prod	認証済みブラウザーによる、本番環境向けの安全なカナリアテスト（読み取り専用のチェック）。
yarn canary:notifications	本番環境のプロバイダーレベルのメール／WhatsApp 通知カナリアテスト。

---

本番環境のカナリアテスト実行

通常の main デプロイでは、マージのたびに誤ってメール／WhatsApp の費用が発生しないよう、本番環境への実送信カナリアテストは意図的に無効になっています。必要に応じて実行するには、GitHub Actions ワークフロー Production Real-Send Canaries を使い、送信する項目を選択します。

• 認証 OTP カナリアテスト
• 通知メール／WhatsApp カナリアテスト

このワークフローでは、まず常に本番環境のスモークテストを実行し、その後、その実行で明示的に選択した実送信カナリアテストのみを実行します。

ログのみのテストと実際のメール／WhatsApp テスト、本番環境で安全に検証する方法、本番環境で実際に送信される公開投稿経路についての全ポリシーは、docs/notification-testing.md を参照してください。

---

ローカルセットアップ

1. インストール

corepack yarn install

このリポジトリでは Node.js 24.18.1 を使用します。依存関係をインストールする前に、.nvmrc で指定された正確なバージョンを使用してください。Node を変更する場合は、Node ランタイムのアップグレード手順書に従い、ローカル開発、CI、型定義、Worker ビルドをまとめて更新してください。

Yarn は、新しい直接依存および推移的依存のパッケージリリースを、公開から 7 日経過してから受け入れます。通常の yarn add および yarn up コマンドには、このルールが自動的に適用されます。CI はパッケージグラフを不変の状態でインストールし、強化されたジョブでレジストリのメタデータを再確認します。

緊急性があり、レビュー済みのセキュリティ修正を適用する場合は、影響を受けるパッケージのみを更新してください。

corepack yarn up <package>@<fixed-version> --no-time-gate

待機期間を回避した勧告とその理由をプルリクエストに記録してください。.yarnrc.yml でパッケージを npmPreapprovedPackages に追加したり、経過日数の制限を無効にしたりしないでください。

2. 環境

.env.example を .env にコピーし、アプリケーションのシークレットを記入してください。これは Nuxt、Wrangler、セットアップスクリプト、E2E テストで共通して使用する唯一のローカル設定ファイルです。セットアップや古い .dev.vars ファイルからの移行については、ローカル開発を参照してください。2 つ目のシークレットファイルやシンボリックリンクは必要ありません。

3. ローカル開発の準備

corepack yarn local:setup

このコマンドは安全に繰り返し実行できます。ローカル D1 を現在のマイグレーション、フィクスチャ、認証情報、外部キーのベースラインに戻し、ローカル開発者用ログイン情報を 1 つ表示します。

URL: http://localhost:3000/login?email=developer%40playwright.example
Email: [email protected]
Password: <fresh value generated by local:setup>

この localhost 限定アカウントは、すべてのキュレーション済みテナントのメンバーであり、プラットフォームダッシュボードにアクセスできます。パスワードはセットアップを実行するたびに生成され、1 度だけ表示され、ローカル D1 にはハッシュとしてのみ保存されます。セットアップを再実行すると既存のローカルセッションが削除されるため、その後は新しく表示されたパスワードで再度サインインしてください。

4. 実行

corepack yarn dev

アプリは http://localhost:3000 で利用できます。

yarn dev は通常のアプリケーション開発ループです。Nitro は wrangler.toml で宣言されたバインディングを読み込み、ローカルの D1／KV／R2 リソースをエミュレートし、Nuxt のホットモジュール置換を維持します。D1 はリセットされません。ローカル D1 を本番スナップショットから復元する場合は、corepack yarn local:setup を実行してください。

テナントのダッシュボードは、URL を推測せず、ダッシュボード UI から開いてください。手動でルートを構築する必要がある場合、ダッシュボードのセグメントにはサブドメインではなく組織の slug を使い、それ以外はすべてその直下に配置します。Kikuzuki のロケーションは /dashboard/org-bVY8SxxUuG6Ctk2CQnfCk8T2cPsj4jJX/locations です。

本番ランタイムでブラウザー検証を行う場合は、生成された Worker をローカルで使用してください。Wrangler は Nuxt と同じ .env を読み込みます。Playwright もこのファイルを読み込み、Worker にテスト専用のローカル URL と配信設定を渡します。

yarn test:e2e:local tests/e2e/tenant-rendering.spec.ts

本番に近いローカル Worker を実行するには：

yarn dev:worker

ビルドが成功した後は、yarn dev:worker:start で再ビルドせずに同じ .output を再起動できます。ソースを編集しても .output は自動的にコンパイルされません。通常の HMR 編集ループには yarn dev を使用してください。

Playwright はローカル D1 スキーマを適用し、使い捨ての E2E アーティファクトを消去し、本番スナップショットを復元し、検証済みの合成 Better Auth アカウントをプロビジョニングし、Cloudflare Worker をビルドしてローカル workerd 上で起動します。認証が必要なテストでは、Playwright プロセス内で生成されたランダムなパスワードを使って Better Auth 経由でサインインします。メール受信トレイや認証バイパス用ルートは関与しません。これらのテスト用認証情報は、手動ログイン用の別経路ではありません。ブラウザーで作業する際は、corepack yarn local:setup によって表示されたローカル開発者アカウントを使用してください。

ローカルのテナントテストでは、共有ホストのルーティング契約を使用します。ブラウザーは localhost を対象とし、テストヘルパーが選択したフィクスチャの x-preview-tenant を設定します。一方、デプロイ済みのステージング環境では、第 1 レベルのテナントエイリアスを直接使用します。これはローカルブラウザーでの正式な検証経路です。Worker のブラウザー検証では、*.localhost への直接アクセスに依存しないでください。

http://localhost:3000/                  (x-preview-tenant: ncls)
http://localhost:3000/services          (x-preview-tenant: ncls)
http://localhost:3000/experiences       (x-preview-tenant: pottery-house)
http://localhost:3000/reservations      (x-preview-tenant: kikuzuki-krabi-thailand)

macOS のファイル上限を修正する

ulimit -n 65536

---

デプロイ

デプロイは .github/workflows/ci.yml のブランチに従います。

1. プルリクエストでは、ローカル Worker と本番環境からコピーしたローカル D1（db:pull:local）に対して、Checks と E2E スイートを実行します。プルリクエストでは何もデプロイされません。
2. staging へのプッシュでは、Checks の実行後、ステージング Worker をデプロイし、ステージングのマイグレーションを適用してから、ステージング環境自体に対して読み取り専用の MCP とテナントのレンダリングを実行します。実際のステージング環境にテストデータを書き込むことはありません。
3. main へのプッシュでは、Checks の実行後、本番 Worker をデプロイし、本番環境のマイグレーションを適用してから、読み取り専用の本番ブラウザー検証を実行します。

CI では、該当するブランチのジョブでのみネイティブの Wrangler コマンドを実行します。

インシデント発生時は、Cloudflare のデプロイ履歴を使用して、D1 のデータを変更せずに、正常稼働が最後に確認された本番デプロイへ戻します。その後、修正を staging と main に反映し、ブラウザーゲートを再実行します。

本番環境のシークレットは、Cloudflare ダッシュボード → Workers & Pages → krabiclaw → Settings → Variables に保存されています。

保護された内部ジョブのシークレットは、Wrangler を使って設定します。

openssl rand -base64 32
yarn wrangler secret put CRON_SECRET

CRON_SECRET は内部のスケジュール済みエンドポイントを保護します。ローカルコマンドは .env から設定を読み込みます。デプロイ済みの Worker は、Cloudflare のシークレットと wrangler.toml の変数を使用します。

MCP の再接続に関するトリアージと Cloudflare の認証デバッグについては、docs/observability.md に記載されています。

必須のデプロイ済みブラウザーリリースゲートと障害復旧ルールについては、docs/operations/release-and-outage-prevention.md に記載されています。

---

スキーマ

server/db/schema.ts が唯一のスキーマの信頼できる情報源です。migrations/ には生成された出力を格納します。手書きのマイグレーションは禁止されています。

---

Stripe（ローカル）

yarn stripe:listen

出力された whsec_... 署名シークレットを .env の STRIPE_WEBHOOK_SECRET にコピーします。デプロイする前に、本番環境の Webhook シークレットに戻してください。

ネイティブのマーケットプレイスのオンボーディングでは、別の Accounts v2 thin-event destination と署名シークレットを使用します。詳しくはStripe Connect のオンボーディングを参照してください。