aranea-sdk-cli 0.1.3 → 0.3.0

package/README.md

@@ -28,11 +28,74 @@ aranea-sdk register --type aranea_ar-is04a --mac AABBCCDDEEFF --dry-run
 
 # スキーマ取得
 aranea-sdk schema get --type aranea_ar-is04a
+
+# AIアシスタントに質問
+aranea-sdk metatron ask "State Reportの送信方法は？"
 ```
 
 ## コマンド一覧
 
-### test - 接続・認証テスト
+| コマンド | 説明 | 認証 |
+|---------|------|------|
+| `test` | 接続・認証テスト | 不要 |
+| `register` | デバイス登録 | 不要（テストテナント） |
+| `schema` | スキーマ取得・State Report検証 | 不要 |
+| `validate` | Type名検証 | 不要 |
+| `simulate` | 状態レポートシミュレーション | 不要 |
+| `mqtt` | コマンド送信・ACKモニタリング | **必要** |
+| `knowledge` | ナレッジベース管理 | **必要** |
+| `metatron` | AI対話アシスタント | **必要** |
+
+---
+
+## 認証設定
+
+### 認証が必要なコマンド
+
+`mqtt`, `knowledge`, `metatron` コマンドは Firebase Auth IDトークンが必要です。
+
+### 認証方法 (3つの選択肢)
+
+#### 1. 環境変数で設定 (推奨)
+
+```bash
+# Firebase IDトークンを環境変数に設定
+export ARANEA_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIsInR5..."
+# または
+export FIREBASE_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIsInR5..."
+
+# コマンド実行
+aranea-sdk metatron ask "State Reportの送信方法は？"
+```
+
+#### 2. --token オプションで指定
+
+```bash
+aranea-sdk metatron ask "質問内容" --token "eyJhbGciOiJSUzI1NiIsInR5..."
+```
+
+#### 3. サービスアカウント (mqtt コマンドのみ)
+
+```bash
+# サービスアカウントキーを環境変数に設定
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"
+# オプション: カスタムAPIキー (未設定時はデフォルト値を使用)
+export FIREBASE_API_KEY="AIzaSy..."
+
+aranea-sdk mqtt send-command -l 3004AABBCCDDEEFF0001 -t relay -p '{"channel":1,"state":true}'
+```
+
+### Firebase IDトークンの取得方法
+
+```javascript
+// Firebase Auth からIDトークンを取得
+const token = await firebase.auth().currentUser.getIdToken();
+console.log(token);
+```
+
+---
+
+## test - 接続・認証テスト
 
 ```bash
 # API接続テスト
@@ -45,7 +108,9 @@ aranea-sdk test auth
 aranea-sdk test auth --tid T123... --lacis-id 173... --cic 022029
 ```
 
-### register - デバイス登録
+---
+
+## register - デバイス登録
 
 ```bash
 # ドライラン (登録せずに検証)
@@ -63,7 +128,7 @@ aranea-sdk register \
   --cic 022029
 ```
 
-#### オプション
+### オプション
 
 | オプション | 説明 | デフォルト |
 |-----------|------|-----------|
@@ -75,17 +140,40 @@ aranea-sdk register \
 | `-d, --dry-run` | 検証のみ | false |
 | `-e, --endpoint` | 環境 | production |
 
-### schema - スキーマ操作
+---
+
+## schema - スキーマ操作
 
 ```bash
-# スキーマ取得
+# スキーマ一覧表示
+aranea-sdk schema list
+
+# スキーマ詳細取得
 aranea-sdk schema get --type aranea_ar-is04a
+aranea-sdk schema get --type aranea_ar-is04a --json  # JSON出力
 
-# スキーマ検証
+# State Report JSONの検証
 aranea-sdk schema validate --file state.json --type aranea_ar-is04a
 ```
 
-### validate - Type名検証
+> **Note**: `schema validate` は State Report ペイロードの検証用です。
+> スキーマ定義ファイル自体の静的検証機能は将来バージョンで追加予定です。
+
+### 実装済み vs 計画中
+
+| サブコマンド | 状態 | 説明 |
+|-------------|------|------|
+| `list` | ✅ 実装済み | 登録済みスキーマ一覧 |
+| `get` | ✅ 実装済み | スキーマ詳細取得 |
+| `validate` | ✅ 実装済み | State Report 検証 |
+| `create` | 🔜 計画中 | スキーマ新規作成 |
+| `push` | 🔜 計画中 | 開発環境へプッシュ |
+| `promote` | 🔜 計画中 | 本番環境へ昇格 |
+| `rollback` | 🔜 計画中 | バージョンロールバック |
+
+---
+
+## validate - Type名検証
 
 ```bash
 # Type名検証
@@ -95,7 +183,9 @@ aranea-sdk validate type --type aranea_ar-is04a
 aranea-sdk validate type --type ISMS_ar-is04a
 ```
 
-### simulate - 状態レポートシミュレーション
+---
+
+## simulate - 状態レポートシミュレーション
 
 ```bash
 # ファイルからシミュレーション
@@ -105,16 +195,178 @@ aranea-sdk simulate state-report --file test.json --dry-run
 aranea-sdk simulate state-report --payload '{"temp": 25.5}'
 ```
 
+---
+
+## mqtt - コマンド送信 (認証必要)
+
+デバイスへのコマンド送信とACK監視を行います。
+
+### send-command - コマンド送信
+
+```bash
+# リレーON (dry-run)
+aranea-sdk mqtt send-command \
+  --lacis-id 3004AABBCCDDEEFF0001 \
+  --type relay \
+  --params '{"channel":1,"state":true}' \
+  --dry-run
+
+# 実際に送信 (ACK待機あり)
+aranea-sdk mqtt send-command \
+  --lacis-id 3004AABBCCDDEEFF0001 \
+  --type relay \
+  --params '{"channel":1,"state":true}' \
+  --token "$ARANEA_AUTH_TOKEN" \
+  --wait
+```
+
+### オプション
+
+| オプション | 説明 | デフォルト |
+|-----------|------|-----------|
+| `-l, --lacis-id` | デバイスLacisID (必須) | - |
+| `-t, --type` | コマンドタイプ (必須) | - |
+| `-p, --params` | パラメータ JSON | `{}` |
+| `--ttl` | TTL秒数 | 30 |
+| `--group-id` | グループID | - |
+| `--token` | 認証トークン | 環境変数から |
+| `-w, --wait` | ACK待機 | false |
+| `--wait-timeout` | ACK待機タイムアウト | 30 |
+| `-d, --dry-run` | リクエスト内容表示のみ | false |
+
+### monitor - ACKモニタリング
+
+```bash
+# 特定コマンドのACK監視
+aranea-sdk mqtt monitor --cmd-id "abc123..." --timeout 60
+
+# デバイス単位で監視 (Firestoreリアルタイム)
+aranea-sdk mqtt monitor --lacis-id 3004AABBCCDDEEFF0001 --timeout 120
+```
+
+> **前提**: Firestoreリアルタイム監視には `GOOGLE_APPLICATION_CREDENTIALS` が必要です。
+
+### periodic - 定期送信 (負荷テスト用)
+
+```bash
+# 5秒間隔で10回送信
+aranea-sdk mqtt periodic \
+  --lacis-id 3004AABBCCDDEEFF0001 \
+  --type ping \
+  --interval 5 \
+  --count 10 \
+  --token "$ARANEA_AUTH_TOKEN"
+```
+
+---
+
+## knowledge - ナレッジベース管理 (認証必要)
+
+AraneaMetatronのナレッジベースを管理します。
+
+### 使用例
+
+```bash
+# ナレッジ一覧
+aranea-sdk knowledge list --token "$ARANEA_AUTH_TOKEN"
+
+# カテゴリ別一覧
+aranea-sdk knowledge list --category api
+
+# 検索
+aranea-sdk knowledge search --query "state report"
+
+# 詳細取得
+aranea-sdk knowledge get --id "entry_id_here"
+
+# ナレッジ追加
+aranea-sdk knowledge add \
+  --title "State Report送信方法" \
+  --category guide \
+  --file ./content.md \
+  --keywords "state,report,api"
+
+# カテゴリ一覧表示
+aranea-sdk knowledge categories
+```
+
+### カテゴリ
+
+| カテゴリ | 説明 |
+|---------|------|
+| `api` | API仕様・エンドポイント |
+| `guide` | 実装ガイド・チュートリアル |
+| `code` | コードサンプル・スニペット |
+| `reference` | リファレンス・仕様書 |
+| `incident` | インシデント・トラブルシューティング |
+| `tip` | Tips・ノウハウ |
+
+---
+
+## metatron - AI対話 (認証必要)
+
+AraneaSDK専門のAIアシスタントに質問できます。
+
+### 使用例
+
+```bash
+# 単発質問
+aranea-sdk metatron ask "State Reportの送信方法は？" --token "$ARANEA_AUTH_TOKEN"
+
+# JSON出力
+aranea-sdk metatron ask "ESP32のサンプルコードは？" --raw
+
+# 対話モード (REPL)
+aranea-sdk metatron chat --token "$ARANEA_AUTH_TOKEN"
+
+# 対話可能なトピック一覧
+aranea-sdk metatron topics
+
+# 質問例を表示
+aranea-sdk metatron examples
+```
+
+### 対話可能なトピック
+
+- State Report API
+- デバイス登録
+- スキーマ設計
+- MQTT/コマンド
+- ESP32実装
+- デバイスタイプ
+- CelestialGlobe
+- トラブルシューティング
+
+---
+
 ## 対応デバイスType
 
+### 新規 (aranea_ar-*)
+
 | Type | ProductType | 説明 |
 |------|-------------|------|
 | `aranea_ar-is01` | 001 | AraneaSDK Basic Sensor |
+| `aranea_ar-is02` | 002 | AraneaSDK Standard Sensor |
 | `aranea_ar-is04a` | 004 | Network Scanner (ESP32) |
 | `aranea_ar-is05a` | 005 | Environment Sensor (ESP32) |
 | `aranea_ar-is06a` | 006 | Power Monitor (ESP32) |
 | `aranea_ar-is10` | 010 | Router Inspector (OpenWrt/AsusWRT) |
 
+### レガシー (ISMS_ar-*)
+
+| Type | ProductType | 説明 |
+|------|-------------|------|
+| `ISMS_ar-is01` | 001 | Basic Sensor (レガシー) |
+| `ISMS_ar-is02` | 002 | Standard Sensor (レガシー) |
+| `ISMS_ar-is03` | 003 | Advanced Sensor (レガシー) |
+| `ISMS_ar-is04` | 004 | Multi-channel Sensor (レガシー) |
+| `ISMS_ar-is05` | 005 | Environment Sensor (レガシー) |
+
+> **Note**: `ISMS_ar-*` プレフィックスは永続的にサポートされます。
+> 登録時に `aranea_ar-*` へ自動変換されます。
+
+---
+
 ## LacisID生成規則
 
 AraneaDeviceのLacisIDは以下の形式で自動生成されます:
@@ -131,6 +383,8 @@ ProductCode: 4桁4進数 (枝番から算出)
 **例**: `aranea_ar-is04a` + MAC `AABBCCDDEEFF`
 → LacisID: `3004AABBCCDDEEFF1201`
 
+---
+
 ## 環境設定
 
 | 環境 | Gate API | State API |
@@ -138,6 +392,8 @@ ProductCode: 4桁4進数 (枝番から算出)
 | production | `asia-northeast1-mobesorder.cloudfunctions.net` | 同左 |
 | staging | `asia-northeast1-mobesorder-staging.cloudfunctions.net` | 同左 |
 
+---
+
 ## テストテナント
 
 開発・テスト用に以下のテストテナントが利用可能です:
@@ -147,25 +403,37 @@ ProductCode: 4桁4進数 (枝番から算出)
 
 テストテナントを使用する場合、`--tid`, `--lacis-id`, `--cic` オプションは省略可能です。
 
-## レガシーType名サポート
+---
 
-`ISMS_ar-*` プレフィックスは永続的にサポートされます:
+## ヘルプ表示
 
 ```bash
-# ISMS_ar-* は aranea_ar-* に自動変換
-aranea-sdk register --type ISMS_ar-is04a --mac AABBCCDDEEFF
-# → typeWarning.suggestedType: "aranea_ar-is04a" で登録
+# 全体ヘルプ
+aranea-sdk --help
+
+# コマンド別ヘルプ
+aranea-sdk schema --help
+aranea-sdk mqtt --help
+aranea-sdk metatron --help
+aranea-sdk knowledge --help
 ```
 
+---
+
 ## 要件
 
 - Node.js >= 18.0.0
 
+---
+
 ## ライセンス
 
 MIT License - see [LICENSE](./LICENSE)
 
+---
+
 ## 関連リンク
 
 - [AraneaSDK Documentation](https://github.com/warusakudeveroper/mobes2.0/tree/main/doc/APPS/araneaSDK)
+- [AraneaMetatron Architecture](https://github.com/warusakudeveroper/mobes2.0/tree/main/doc/APPS/araneaSDK/headDesign/20_ARANEA_METATRON_ARCHITECTURE.md)
 - [Issues](https://github.com/warusakudeveroper/mobes2.0/issues)

package/dist/commands/knowledge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * knowledge コマンド - ナレッジベース管理
+ *
+ * Usage:
+ *   aranea-sdk knowledge add --title "..." --content "..." --category guide
+ *   aranea-sdk knowledge search --query "state report"
+ *   aranea-sdk knowledge list --category api
+ *   aranea-sdk knowledge get --id <id>
+ *
+ * @see doc/APPS/araneaSDK/headDesign/20_ARANEA_METATRON_ARCHITECTURE.md
+ */
+import { Command } from 'commander';
+export declare const knowledgeCommand: Command;
+export default knowledgeCommand;