kaiord

Kaiord — オープンソースの健康・フィットネスデータフレームワーク

kaiord.com | エディター | npm

Kaiord は、健康・フィットネスデータの作成、変換、管理を行うオープンソースのフレームワークです。

以下を提供します。

• @kaiord/core：.fit、.tcx、.zwo、.krd（Kaiord）ファイル用のフォーマットアダプターと、Garmin Connect API 統合を備えた TypeScript ライブラリです。
• @kaiord/cli：複数のフォーマット間でファイルを変換、検証、比較するコマンドラインツールです。
• @kaiord/mcp：Kaiord のツールを AI エージェント（Claude Desktop、Claude Code など）に提供する MCP サーバーです。公式 MCP レジストリに io.github.pablo-albaladejo/kaiord として公開されています。
• ワークアウトエディター：ワークアウトファイルを視覚的に作成・編集できる Web アプリケーションです。

---

✨ 機能

• ビジュアルワークアウトエディター - ブラウザー上でワークアウトを作成・編集できます
• .krd（Kaiord Representation Definition）形式の統一された JSON ベースのフォーマット
• スキーマ検証（Zod）
• FIT / TCX / ZWO / GCN / KRD 間のラウンドトリップ安全な変換
• ヘキサゴナルアーキテクチャと、完全に型付けされた API

対応する FIT フィールド

ワークアウトのメタデータ

• サブスポーツ分類：詳細なスポーツ種目（トレイルランニング、インドアサイクリング、ラップスイミングなど）
• プールの寸法：水泳ワークアウトのプールの長さと単位

ワークアウトのステップ

• コーチングメモ：各ステップの指示テキスト（最大 256 文字）
• 水泳用具：フィン、キックボード、パドル、プルブイ、シュノーケル

継続時間の種類

• 時間と距離：標準的なインターバルの継続時間
• カロリーベース：指定したカロリーを消費すると終了するステップ
• パワーベース：パワーのしきい値（ワット）に基づいて終了するステップ
• 心拍数条件：心拍数のしきい値（bpm）に基づいて終了するステップ
• 繰り返し条件：時間、距離、カロリー、心拍数、パワーの目標に達するまで繰り返すブロック

既知の制限事項

• トレーニングストレススコア（TSS）：training_peaks_tss の継続時間の種類は、FIT コンバーターにまだ実装されていません。これは TrainingPeaks 固有の指標であり、追加のマッピングロジックが必要です。貢献を歓迎します！

---

🔒 ローカルファーストアーキテクチャ

Kaiord はローカルファーストです。データを送信する Kaiord サーバーが存在しないため、データはお使いのデバイスに保存されます。アカウントもバックエンドもありません。

• データはブラウザーの IndexedDB に保存されます。 Workout Editor は、すべてのワークアウト、テンプレート、プロフィール、設定をローカルの Dexie.js / IndexedDB データベース（dexie-database.ts 内の new KaiordDatabase()）に保存し、UI は useLiveQuery を通じてリアクティブに読み込みます。リモートデータベースには何も書き込まれません。詳しくは、State Management の「Persisted data → Dexie」ルールをご覧ください。
• 変換はすべてお使いのマシン上で実行されます。 FIT / TCX / ZWO / GCN ↔ KRD の変換はプロセス内で実行されます。エディターではクライアント側（import-workout-formats.ts、export-workout-formats.ts）、または @kaiord/cli ではローカルで処理されます。変換のためにファイルがお使いのデバイスから外部に送信されることはありません。
• 同期はオプトインで、お客様ご自身のクラウドに保存されます。 データがデバイスから外部に送信されるのは、Google Drive に接続した場合のみです。cloud-sync アダプター は Google Identity Services の drive.appdata スコープを使用するため、同期データはお客様ご自身の Drive のアプリフォルダーに保存されます。アクセストークンはセッション中のみメモリー内に保持され、Kaiord によって永続化されることはありません。
• 連携にはお客様がログイン中のセッションを使用します。認証情報のプロキシはありません。 Garmin、WHOOP、Train2Go は、既存のブラウザーセッションを利用するブラウザー拡張機能の「ブリッジ」（garmin-bridge、whoop-bridge、train2go-bridge）を介して接続します。openspec/specs/adapter-contracts/spec.md に従い、ブリッジは「ユーザーの認証情報を保存、送信、管理してはならない」ものとします。認証は「全面的にブラウザーの Cookie jar に委任」されます。認証情報やデータをプロキシするサードパーティサーバーはありません。
• オフラインで動作します。 すべてのロジックとストレージがクライアント側にあるため、読み込み後はネットワーク接続がなくてもエディターを使い続けられます。

---

📚 ドキュメント

包括的なドキュメントは /docs ディレクトリにあります。

• はじめに - ライブラリーと CLI のインストール、基本的な使い方、すぐに試せるサンプル
• アーキテクチャ - ヘキサゴナルアーキテクチャ、ポート＆アダプターパターン、設計原則
• テスト - テスト戦略、TDD ワークフロー、カバレッジ要件
• デプロイ - CI/CD パイプライン、GitHub Pages へのデプロイ、npm への公開
• 貢献 - 貢献ガイドライン、開発ワークフロー、コード規約
• KRD フォーマット - Kaiord Representation Definition フォーマットの完全な仕様
• AI エージェント - AI を活用した開発のガイダンス

---

🧩 技術スタック

レイヤー	ツール類
コア	TypeScript, tsdown, Zod
CLI	yargs
Web アプリ	React, Zustand, Tailwind, Radix UI
テスト	Vitest, Playwright
パッケージマネージャー	pnpm

---

🏗 モノレポの構成

kaiord/
├─ packages/
│  ├─ core/                → domain types, schemas, ports & use cases
│  ├─ fit/                 → Garmin FIT format adapter
│  ├─ tcx/                 → Training Center XML adapter
│  ├─ zwo/                 → Zwift ZWO format adapter
│  ├─ garmin/              → Garmin Connect API adapter
│  ├─ cli/                 → command-line interface
│  ├─ mcp/                 → MCP server for AI/LLM integration
│  └─ workout-spa-editor/  → web application (https://kaiord.com/app/)
├─ docs/   → documentation
├─ LICENSE
├─ README.md
└─ pnpm-workspace.yaml

---

🚀 クイックスタート

Web アプリを試す

Workout Editor を起動 →

ブラウザー上でワークアウトを視覚的に作成、編集できます。インストールは不要です。

ライブラリーを使う

pnpm install
pnpm -r build
pnpm -r test

# Example usage
pnpm kaiord --help

詳しいインストール手順と使用例については、**はじめにガイド**をご覧ください。

---

🚀 CI/CD パイプライン

Kaiord は継続的インテグレーションとデプロイに GitHub Actions を使用しています。

• 自動テスト：Node.js 22.x（メンテナンス LTS）と 24.x（アクティブ LTS）での複数バージョンテスト
• コード品質：ESLint、Prettier、TypeScript の strict モード検証
• リリースの自動化：バージョン管理と npm への公開に Changesets を使用
• セキュリティ：週次の依存関係の脆弱性監査、CodeQL の静的解析、自動依存関係更新

CI/CD の完全なドキュメント、デプロイガイド、npm への公開手順については、**デプロイ**をご覧ください。

機械的な不変条件のガード

lint に加え、このリポジトリでは scripts/ 配下にある60 以上の専用ガードスクリプトで、アーキテクチャと規約を適用しています。各スクリプトには同じ場所に専用のテストスイートがあります。これらはすべてのコミット（husky の pre-commit）と CI（pnpm test:scripts）で実行され、次のような項目を検査します。

• ヘキサゴナルアーキテクチャ — レイヤーの純粋性、アダプターの分離、packages/core/src/ ディレクトリの許可リスト（check-architecture.mjs）
• パッケージの依存関係グラフ — すべての @kaiord/* 依存関係が仕様テーブルと一致すること（check-package-deps.mjs）
• テスト規約 — すべてのテストで should を先頭に付けたタイトルと Arrange/Act/Assert の構造を使用すること（check-test-title-should.mjs、check-test-aaa.mjs）
• プライバシー — トーストやコンソールログに実行時の値を補間しないこと（check-no-pii-leakage.mjs）
• 状態管理の規律 — Zustand ストアが永続化を直接書き込まないこと（check-no-zustand-writethrough.mjs）
• 仕様の整合性 — OpenSpec 形式、アーカイブ日付、自動生成インデックスの同期（check-spec-format.mjs、check-archive-*.mjs）

ここで重要なルールは、スクリプトによって強制されます。ドキュメントはルールを説明しますが、それを確実に守らせるのはガードです。

貢献

Kaiord に貢献するには、次の手順に従ってください。

1. リポジトリをフォークしてクローンする
2. 機能ブランチを作成する：git checkout -b feature/my-feature
3. コードスタイルのガイドラインに沿って変更を加える
4. changeset を追加する：pnpm exec changeset（バージョンに影響する変更の場合）
5. ローカルでテストする：pnpm -r test と pnpm -r build
6. PR を提出する：マージ前にすべてのチェックに合格する必要があります

詳しい貢献ガイドライン、開発ワークフロー、コード標準については、**貢献ガイド**をご覧ください。

---

📚 参考資料とリソース

フォーマット仕様

• Garmin FIT SDK (JavaScript) - FIT プロトコルの公式実装
• FIT Workout Files Cookbook - ワークアウトファイルのエンコードガイド
• FIT File Types: Workout - ワークアウトファイル形式の仕様
• Training Center XML (TCX) - Garmin の XML ベースのフォーマット
• TCX Schema (XSD) - Garmin 公式の TCX スキーマ定義
• Zwift Workout Format (ZWO) - Zwift の XML ベースのワークアウト形式

---

❤️ サポート

Kaiord が役に立った場合は、開発への支援をご検討ください。

• ⭐ 他の人にも見つけてもらえるよう、このリポジトリにスターを付ける
• 💖 GitHub でスポンサーになる
• ☕ コーヒーをおごる

皆さまの支援は、フィットネスコミュニティのために Kaiord を維持・改善する助けになります。

Pablo Albaladejo が制作

---

📜 ライセンス

MIT © 2025 Pablo Albaladejo 詳細は LICENSE をご覧ください。