aranea-sdk-cli 0.3.1 → 0.3.3

package/README.md

@@ -4,6 +4,65 @@
 
 AraneaSDK CLI - ESP32 IoTデバイス開発支援ツール
 
+---
+
+## 🤖 AIエージェント向けガイド
+
+> **AIエージェント (Claude, Codex, etc.) がAraneaSDK関連タスクを実行する際は、このCLIを使用してください。**
+
+### ナレッジ追加 (ローカルファイルではなくCLI経由で)
+
+```bash
+# ❌ ローカルファイル作成ではなく
+# ✅ CLIでナレッジベースに追加
+aranea-sdk knowledge add \
+  --title "ESP32 HTTPSタイムアウト設定" \
+  --category tip \
+  --content "ESP32でHTTPS接続する場合、最低15秒のタイムアウトが必要。初回SSL handshakeは特に時間がかかる。" \
+  --keywords "esp32,https,timeout,ssl"
+```
+
+### Metatronへの質問 (AIアシスタント連携)
+
+```bash
+# AraneaSDK専門AIに質問
+aranea-sdk metatron ask "ESP32のHTTPSタイムアウトのベストプラクティスは？"
+
+# 対話モード
+aranea-sdk metatron chat
+```
+
+### 典型的なワークフロー
+
+1. **問題解決時**: `metatron ask "問題の説明"` で既存ナレッジを確認
+2. **新知見発見時**: `knowledge add` でナレッジベースに追加
+3. **デバイス登録時**: `register --dry-run` で検証後、実登録
+
+### 🔴 特に貴重なナレッジ（必ず追加すべき）
+
+以下の情報は一般ドキュメントでは得られない**実践的知見**です。
+発見次第、CLIでナレッジベースに追加してください：
+
+| カテゴリ | 追加すべき情報 | 例 |
+|---------|--------------|-----|
+| `incident` | ハードウェア固有の問題・解決策 | メモリ不足でクラッシュ、タイムアウトエラー |
+| `tip` | テスト・デバッグで追い込んだパラメータ | HTTPSタイムアウト15秒必要 |
+| `tip` | ESP32メモリ関連設定 | SSL接続に50KB必要 |
+| `tip` | SBC (OrangePi等) のサービス起動・権限問題 | systemd設定、sudoers設定 |
+| `incident` | ハードウェア相性問題 | 特定WiFiモジュールとの非互換 |
+
+```bash
+# 例: インシデント対応で発見した設定値を追加
+aranea-sdk knowledge add \
+  --title "ESP32 HTTPSタイムアウト 15秒必要" \
+  --category tip \
+  --content "ESP32でHTTPS接続する場合、最低15秒のタイムアウトが必要。初回SSL handshakeは特に時間がかかる。-11 READ_TIMEOUTエラーの原因。" \
+  --keywords "esp32,https,timeout,ssl,handshake" \
+  --device-types "aranea_ar-is04a,aranea_ar-is05a"
+```
+
+---
+
 ## 概要
 
 AraneaSDK CLIは、AraneaSDK対応ESP32デバイスの開発・テスト・登録を支援するコマンドラインツールです。
@@ -39,12 +98,13 @@ aranea-sdk metatron ask "State Reportの送信方法は？"
 |---------|------|------|
 | `test` | 接続・認証テスト | 不要 |
 | `register` | デバイス登録 | 不要（テストテナント） |
-| `schema` | スキーマ取得・State Report検証 | 不要 |
+| `schema` | スキーマ取得・検証・プッシュ | push/promote時必要 |
 | `validate` | Type名検証 | 不要 |
 | `simulate` | 状態レポートシミュレーション | 不要 |
 | `mqtt` | コマンド送信・ACKモニタリング | **必要** |
 | `knowledge` | ナレッジベース管理 | **必要** |
 | `metatron` | AI対話アシスタント | **必要** |
+| `auth` | 認証トークン管理 | - |
 
 ---
 
@@ -166,11 +226,27 @@ aranea-sdk schema validate --file state.json --type aranea_ar-is04a
 | `list` | ✅ 実装済み | 登録済みスキーマ一覧 |
 | `get` | ✅ 実装済み | スキーマ詳細取得 |
 | `validate` | ✅ 実装済み | State Report 検証 |
-| `create` | 🔜 計画中 | スキーマ新規作成 |
-| `push` | 🔜 計画中 | 開発環境へプッシュ |
-| `promote` | 🔜 計画中 | 本番環境へ昇格 |
+| `validate-schema` | ✅ 実装済み | スキーマ定義の静的検証 |
+| `push` | ✅ 実装済み | 開発環境へプッシュ (認証必要) |
+| `promote` | ✅ 実装済み | 本番環境へ昇格 (認証必要、確認ステップあり) |
+| `info` | ✅ 実装済み | スキーマ詳細情報・リビジョン履歴 |
 | `rollback` | 🔜 計画中 | バージョンロールバック |
 
+### 環境切替 (v0.3.1)
+
+すべてのschemaサブコマンドで `--endpoint` オプションが使用可能です:
+
+```bash
+# デフォルト: staging
+aranea-sdk schema list
+
+# 明示的にproduction指定
+aranea-sdk schema list --endpoint production
+
+# 環境変数でも指定可能
+ARANEA_ENV=production aranea-sdk schema list
+```
+
 ---
 
 ## validate - Type名検証
@@ -339,6 +415,45 @@ aranea-sdk metatron examples
 
 ---
 
+## auth - 認証管理 (v0.3.1)
+
+Firebase Auth IDトークンを管理します。トークンは `~/.aranea-sdk/credentials.json` に保存されます。
+
+### 使用例
+
+```bash
+# ログイン (対話式)
+aranea-sdk auth login
+
+# メールアドレス指定でログイン
+aranea-sdk auth login --email dev@example.com
+
+# トークン情報表示
+aranea-sdk auth token
+
+# トークンのみ出力 (スクリプト用)
+aranea-sdk auth token --raw
+
+# トークン更新 (1時間で期限切れ)
+aranea-sdk auth refresh
+
+# ログアウト
+aranea-sdk auth logout
+```
+
+### トークンライフサイクル
+
+- IDトークンは **1時間** で期限切れ
+- `auth refresh` で新しいトークンを取得
+- `auth token --raw` でスクリプトからトークン取得可能
+
+```bash
+# 他コマンドでトークンを使用
+aranea-sdk metatron ask "質問" --token "$(aranea-sdk auth token --raw)"
+```
+
+---
+
 ## 対応デバイスType
 
 ### 新規 (aranea_ar-*)

package/dist/commands/knowledge.js

@@ -54,10 +54,17 @@ const ora_1 = __importDefault(require("ora"));
 const axios_1 = __importDefault(require("axios"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const config_1 = require("../config");
 // ============================================================================
 // Config
 // ============================================================================
-const KNOWLEDGE_API_BASE = 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaSDK_knowledgeManagement';
+const KNOWLEDGE_API_ENDPOINTS = {
+    production: 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaKnowledgeManagement',
+    staging: 'https://asia-northeast1-mobesorder-staging.cloudfunctions.net/araneaKnowledgeManagement',
+};
+function getKnowledgeApiBase(env) {
+    return KNOWLEDGE_API_ENDPOINTS[env];
+}
 // カテゴリ定義
 const CATEGORIES = ['api', 'guide', 'code', 'reference', 'incident', 'tip'];
 // ============================================================================
@@ -72,8 +79,9 @@ function getAuthToken() {
 /**
  * API呼び出し（Callable形式）
  */
-async function callKnowledgeAPI(action, params, token) {
-    const response = await axios_1.default.post(KNOWLEDGE_API_BASE, { data: { action, ...params } }, {
+async function callKnowledgeAPI(action, params, token, env) {
+    const apiBase = getKnowledgeApiBase(env);
+    const response = await axios_1.default.post(apiBase, { data: { action, ...params } }, {
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
@@ -131,9 +139,12 @@ exports.knowledgeCommand
     .option('--device-types <types>', '関連デバイスタイプ (カンマ区切り)')
     .option('--status <status>', 'ステータス (draft|published)', 'draft')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Add ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        (0, config_1.warnIfProduction)(env, 'knowledge add');
+        console.log(chalk_1.default.bold(`\n=== Knowledge Add (${env}) ===\n`));
         // 認証トークン
         const token = options.token || getAuthToken();
         if (!token) {
@@ -186,7 +197,7 @@ exports.knowledgeCommand
                 relatedDeviceTypes: deviceTypes,
                 status: options.status,
             },
-        }, token);
+        }, token, env);
         spinner.stop();
         if (result.success) {
             console.log(chalk_1.default.green('✓ ナレッジエントリを追加しました'));
@@ -194,6 +205,7 @@ exports.knowledgeCommand
             console.log(`   Title: ${options.title}`);
             console.log(`   Category: ${options.category}`);
             console.log(`   Status: ${options.status}`);
+            console.log(`   Environment: ${env}`);
         }
         else {
             console.log(chalk_1.default.red(`✗ 追加失敗: ${result.error}`));
@@ -212,9 +224,11 @@ exports.knowledgeCommand
     .option('-c, --category <category>', 'カテゴリフィルタ')
     .option('-l, --limit <limit>', '結果数', '10')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Search ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        console.log(chalk_1.default.bold(`\n=== Knowledge Search (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
@@ -225,7 +239,7 @@ exports.knowledgeCommand
             query: options.query,
             category: options.category,
             limit: parseInt(options.limit, 10),
-        }, token);
+        }, token, env);
         spinner.stop();
         if (result.success && result.data) {
             const entries = Array.isArray(result.data) ? result.data : [];
@@ -254,9 +268,11 @@ exports.knowledgeCommand
     .option('-s, --status <status>', 'ステータスフィルタ (draft|published|archived)')
     .option('-l, --limit <limit>', '表示数', '20')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge List ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        console.log(chalk_1.default.bold(`\n=== Knowledge List (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
@@ -267,7 +283,7 @@ exports.knowledgeCommand
             category: options.category,
             status: options.status,
             limit: parseInt(options.limit, 10),
-        }, token);
+        }, token, env);
         spinner.stop();
         if (result.success && result.data) {
             const entries = Array.isArray(result.data) ? result.data : [];
@@ -294,16 +310,18 @@ exports.knowledgeCommand
     .description('ナレッジエントリを取得')
     .requiredOption('-i, --id <id>', 'エントリID')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Get ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        console.log(chalk_1.default.bold(`\n=== Knowledge Get (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
             process.exit(1);
         }
         const spinner = (0, ora_1.default)('ナレッジを取得中...').start();
-        const result = await callKnowledgeAPI('get', { id: options.id }, token);
+        const result = await callKnowledgeAPI('get', { id: options.id }, token, env);
         spinner.stop();
         if (result.success && result.data) {
             formatEntry(result.data, true);
@@ -323,10 +341,13 @@ exports.knowledgeCommand
     .description('ナレッジエントリを削除 (アーカイブ)')
     .requiredOption('-i, --id <id>', 'エントリID')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .option('-y, --yes', '確認をスキップ')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Delete ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        (0, config_1.warnIfProduction)(env, 'knowledge delete');
+        console.log(chalk_1.default.bold(`\n=== Knowledge Delete (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
@@ -338,7 +359,7 @@ exports.knowledgeCommand
             // Note: In a real CLI, would use inquirer for confirmation
         }
         const spinner = (0, ora_1.default)('削除中...').start();
-        const result = await callKnowledgeAPI('delete', { id: options.id }, token);
+        const result = await callKnowledgeAPI('delete', { id: options.id }, token, env);
         spinner.stop();
         if (result.success) {
             console.log(chalk_1.default.green('✓ ナレッジエントリをアーカイブしました'));
@@ -355,20 +376,74 @@ exports.knowledgeCommand
 // knowledge categories
 exports.knowledgeCommand
     .command('categories')
-    .description('利用可能なカテゴリ一覧')
+    .description('利用可能なカテゴリ一覧と追加すべきナレッジの例')
     .action(() => {
     console.log(chalk_1.default.bold('\n=== Knowledge Categories ===\n'));
-    const categoryDescriptions = {
-        api: 'API仕様・エンドポイント',
-        guide: '実装ガイド・チュートリアル',
-        code: 'コードサンプル・スニペット',
-        reference: 'リファレンス・仕様書',
-        incident: 'インシデント・トラブルシューティング',
-        tip: 'Tips・ノウハウ',
+    const categoryInfo = {
+        api: {
+            desc: 'API仕様・エンドポイント',
+            examples: [
+                'State Report API の仕様変更',
+                'エンドポイントURL・認証方式',
+            ],
+        },
+        guide: {
+            desc: '実装ガイド・チュートリアル',
+            examples: [
+                'ESP32 State Report実装手順',
+                'OrangePi サービス設定ガイド',
+            ],
+        },
+        code: {
+            desc: 'コードサンプル・スニペット',
+            examples: [
+                'Arduino HTTPS接続コード',
+                'Python MQTT受信サンプル',
+            ],
+        },
+        reference: {
+            desc: 'リファレンス・仕様書',
+            examples: [
+                'スキーマ定義一覧',
+                'エラーコード一覧',
+            ],
+        },
+        incident: {
+            desc: 'インシデント・トラブルシューティング',
+            examples: [
+                '⚠️ ハードウェア固有の問題・解決策',
+                '⚠️ メモリ不足・タイムアウト事例',
+                '⚠️ 相性問題・回避策',
+            ],
+        },
+        tip: {
+            desc: 'Tips・ノウハウ（一般情報では得られない実践知見）',
+            examples: [
+                '⚠️ ESP32 HTTPSタイムアウト 15秒必要',
+                '⚠️ OrangePi サービス起動順序',
+                '⚠️ メモリ設定・バッファサイズの追い込み値',
+                '⚠️ ハードウェア相性・非互換情報',
+            ],
+        },
     };
     for (const cat of CATEGORIES) {
-        console.log(`  ${chalk_1.default.cyan(cat.padEnd(12))} ${categoryDescriptions[cat]}`);
+        const info = categoryInfo[cat];
+        console.log(`  ${chalk_1.default.cyan(cat.padEnd(12))} ${info.desc}`);
+        for (const ex of info.examples) {
+            if (ex.startsWith('⚠️')) {
+                console.log(`                 ${chalk_1.default.yellow(ex)}`);
+            }
+            else {
+                console.log(`                 ${chalk_1.default.gray('- ' + ex)}`);
+            }
+        }
+        console.log('');
     }
-    console.log('');
+    console.log(chalk_1.default.bold('📝 AIエージェント向け: 以下のナレッジは特に貴重です\n'));
+    console.log(chalk_1.default.yellow('  • インシデント対応で発見したハードウェア固有の設定値'));
+    console.log(chalk_1.default.yellow('  • テスト・デバッグで追い込んだパラメータ（タイムアウト、バッファサイズ等）'));
+    console.log(chalk_1.default.yellow('  • ESP32のメモリ関連、SBCのサービス起動・権限問題'));
+    console.log(chalk_1.default.yellow('  • ハードウェア相性問題と回避策'));
+    console.log(chalk_1.default.yellow('  • 一般的なドキュメントには載っていない実践的知見\n'));
 });
 exports.default = exports.knowledgeCommand;

package/dist/commands/metatron.js

@@ -51,10 +51,17 @@ const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
 const axios_1 = __importDefault(require("axios"));
 const readline = __importStar(require("readline"));
+const config_1 = require("../config");
 // ============================================================================
 // Config
 // ============================================================================
-const METATRON_API_BASE = 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaSDK_metatronQuery';
+const METATRON_API_ENDPOINTS = {
+    production: 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaMetatronQuery',
+    staging: 'https://asia-northeast1-mobesorder-staging.cloudfunctions.net/araneaMetatronQuery',
+};
+function getMetatronApiBase(env) {
+    return METATRON_API_ENDPOINTS[env];
+}
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -67,8 +74,9 @@ function getAuthToken() {
 /**
  * Metatron API呼び出し
  */
-async function queryMetatron(query, context, token) {
-    const response = await axios_1.default.post(METATRON_API_BASE, { data: { query, context } }, {
+async function queryMetatron(query, context, token, env) {
+    const apiBase = getMetatronApiBase(env);
+    const response = await axios_1.default.post(apiBase, { data: { query, context } }, {
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
@@ -110,11 +118,13 @@ exports.metatronCommand
     .description('単発質問')
     .option('--context <context>', 'コンテキスト', 'aranea_sdk_cli')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .option('--raw', 'JSON出力')
     .action(async (question, options) => {
     try {
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
         if (!options.raw) {
-            console.log(chalk_1.default.bold('\n=== AraneaMetatron ===\n'));
+            console.log(chalk_1.default.bold(`\n=== AraneaMetatron (${env}) ===\n`));
             console.log(chalk_1.default.gray(`Q: ${question}`));
         }
         const token = options.token || getAuthToken();
@@ -123,7 +133,7 @@ exports.metatronCommand
             process.exit(1);
         }
         const spinner = options.raw ? null : (0, ora_1.default)('回答生成中...').start();
-        const result = await queryMetatron(question, options.context, token);
+        const result = await queryMetatron(question, options.context, token, env);
         spinner?.stop();
         if (options.raw) {
             console.log(JSON.stringify(result, null, 2));
@@ -143,8 +153,10 @@ exports.metatronCommand
     .description('対話モード (REPL)')
     .option('--context <context>', 'コンテキスト', 'aranea_sdk_cli')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
-    console.log(chalk_1.default.bold('\n=== AraneaMetatron Chat ===\n'));
+    const env = (0, config_1.resolveEnvironment)(options.endpoint);
+    console.log(chalk_1.default.bold(`\n=== AraneaMetatron Chat (${env}) ===\n`));
     console.log(chalk_1.default.gray('AraneaSDKについて質問してください。'));
     console.log(chalk_1.default.gray('終了するには "exit" または Ctrl+C を入力\n'));
     const token = options.token || getAuthToken();
@@ -171,7 +183,7 @@ exports.metatronCommand
             const spinner = (0, ora_1.default)('').start();
             spinner.text = '';
             try {
-                const result = await queryMetatron(query, options.context, token);
+                const result = await queryMetatron(query, options.context, token, env);
                 spinner.stop();
                 console.log('');
                 console.log(chalk_1.default.green('Metatron:'), result.answer);

package/dist/index.js

@@ -28,7 +28,7 @@ const program = new commander_1.Command();
 program
     .name('aranea-sdk')
     .description('AraneaSDK CLI - デバイス開発支援ツール')
-    .version('0.3.1');
+    .version('0.3.3');
 // test コマンド
 program.addCommand(test_1.testCommand);
 // simulate コマンド

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aranea-sdk-cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "AraneaSDK CLI - ESP32 IoTデバイス開発支援ツール",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",