UsaconCLI - コマンドラインインターフェース

概要

デジタル経営コンサルティングアプリ「ウサコン」のCLIインターフェース。 ターミナルから企業管理、AI分析実行、チャット、補助金検索、レポートエクスポート、経営戦略、インサイトなどの操作を実行できる。 引数なしで起動するとInk/React製のインタラクティブTUIモードが立ち上がる。

トリガー: usacon-cli, UsaconCLI, CLIコマンド, usaconコマンド, @usacon/cli

プロジェクト情報

パッケージ依存関係

@usacon/app-core → @usacon/api-client → @usacon/cli

• app-core: 型定義、定数（EXIT_CODES, CREDIT_COSTS）、Zodスキーマ
• api-client: UsaconHttpClient、SSEパーサー、エラー型
• usacon-cli: コマンド実装、TUI、セッション管理

インストール・セットアップ

開発用セットアップ

cd C:\Users\zooyo\Documents\GitHub\DX\digital-management-consulting-app\packages\usacon-cli
npm install    # 依存関係インストール
npm run build  # tsupでビルド（dist/ に出力）
npm link       # グローバルコマンドとして登録
usacon --help  # 動作確認

重要な注意点

• コード変更後は npm run build && npm link が必要（ソース直接実行ではない）
• tsup.config.ts で noExternal: ['@usacon/api-client', '@usacon/app-core'] — ワークスペースパッケージをバンドルに含む
• ビルド成果物: dist/cli.js（bin）、dist/index.js（ESM）、dist/index.cjs（CJS）

npmパッケージとしてインストール（利用者向け）

npm install -g @usacon/cli        # 初回インストール
npm update -g @usacon/cli         # 更新
npm install -g @usacon/cli@latest # 最新版強制インストール

ビルド・テスト・リント

npm公開・バージョン更新フロー

npm run build              # ビルド確認
npm pack --dry-run         # パッケージ内容確認（28ファイル、190.7KB）
npm version patch          # バージョン更新（patch/minor/major）
npm publish --access public  # 公開（@usacon スコープのため --access public 必須）

2FA バイパス（Windows Hello/パスキー環境）

npm の 2FA が Windows Hello/パスキーで設定されている場合、CLI から OTP を生成できない。 Granular Access Token の 2FA バイパス機能を使う：

1. npmjs.com → Settings → Security → 2FA レベルを「Require 2FA or granular token with bypass」に変更・保存
2. Access Tokens → Granular Access Token → Bypass 2FA チェック ON → 生成
3. npm publish --access public --//registry.npmjs.org/:_authToken=<granular-token>

注意: 通常の Classic Token では 2FA バイパス不可。必ず Granular Token を使用する。

CLI修正のリリースフロー（パイプラインとの統合）

コード修正 → テスト → PR → staging merge → E2E → Issue close
→ staging→main merge → Vercel Production Ready
→ package.json version bump → npm run build → npm publish
→ ユーザーに `npm update -g @usacon/cli` を案内

グローバルオプション

コマンド一覧

認証・セッション

設定管理

有効なキー: locale, theme, timezone, max_tokens, selected_company_id

企業管理

company edit オプション:

• --name <name> — 企業名
• --industry <industry> — 業界
• --size <size> — 規模（small/medium/large）
• --employees <n> — 従業員数
• --revenue <n> — 売上高

AI分析

分析の前提条件:

• P1-1（transformation）→ P1-2（maturity）→ CSF → digital-strategy の順序依存あり
• クレジット不足時は402エラー

チャット

• Markdown応答はmarked-terminalでレンダリング
• <human_input> XMLラップでプロンプトインジェクション対策
• --json でNDJSON形式のイベントストリーム出力

クレジット

補助金

favorite add オプション:

• --name <name> — 補助金名（省略時はAPI自動取得）
• --memo <memo> — メモ
• --company-id <companyId> — 企業と関連付け

ジョブ管理

レポート

report export オプション:

• --format <format> — 出力形式: pdf, md, pptx（デフォルト: md）
• -o, --output <path> — 出力ファイルパス

データエクスポート

共通オプション（必須）:

• --company <id> — 企業ID
• --type <type> — 分析タイプ（transformation/maturity/csf/digital-strategy）

任意オプション:

• -o, --output <path> — 出力ファイルパス（省略時はデフォルトファイル名）

バッチ分析

バッチオプション:

• --input <file> (必須): JSONL入力ファイル（10MBサイズ上限）
• --concurrency <n>: 並列度 1-5（デフォルト: 1、現在は逐次実行）
• --retry-failed: 前回失敗した項目のみ再試行（.usacon-batch-state.json から読み込み）
• --dry-run: 実行せずクレジット消費量の見積もりのみ表示

JSONL入力形式:

{"companyId": "uuid-here", "analysisType": "transformation"}
{"companyId": "uuid-here", "analysisType": "maturity"}

経営戦略

インサイト

スレッド管理

エイリアス早見表

インタラクティブTUIモード

起動方法

usacon           # 引数なしで起動（TTY環境のみ）
usacon --verbose # デバッグ出力付きで起動

• 非TTY環境（パイプ、CI）ではヘルプテキストにフォールバック
• Ink + React を動的インポート（コマンドモード起動時間 < 500ms を維持）

TUIコンポーネント構成

App.tsx
  +-- Header.tsx          # タイトル + バージョン
  +-- CompanySelector.tsx  # Tab/矢印で企業選択
  +-- MessageArea.tsx      # チャットメッセージ表示
  +-- InputArea.tsx        # テキスト入力 + 送信
  +-- StatusBar.tsx        # ストリーミング状態表示

キーボードショートカット

状態管理

• useReducer でTUI全体の状態を管理（src/tui/reducer.ts）
• SSEストリーミングでリアルタイム応答表示
• fetchCompanies / sendMessage はprops注入でHTTP/認証レイヤーと疎結合

認証・設定

認証フロー

1. usacon login でEmail/Password入力（対話形式 or 環境変数）
2. Supabase signInWithPassword でトークン取得
3. AES-256-GCM暗号化で ~/.usacon/credentials.json に保存
4. 以降のコマンドでトークンを自動読み込み・リフレッシュ（ensureFreshToken()）

設定ファイルの優先順位

1. 環境変数（最優先）
2. 設定ファイル: ~/.usacon/config.json
3. ビルトインデフォルト: 本番Supabaseプロジェクト

環境変数

ファイル構造

ディレクトリ構成

packages/usacon-cli/
  +-- src/
  |   +-- cli.ts                  # binエントリポイント（#!/usr/bin/env node）
  |   +-- index.ts                # ライブラリエントリポイント + run()
  |   +-- commands/
  |   |   +-- index.ts            # 全コマンドのre-export
  |   |   +-- config.ts           # 設定管理（getConfig/saveConfig）
  |   |   +-- login.ts            # usacon login
  |   |   +-- logout.ts           # usacon logout
  |   |   +-- status.ts           # usacon status
  |   |   +-- company.ts          # usacon company (list/show/new/import/edit/delete/duplicate/limit)
  |   |   +-- analyze.ts          # usacon analyze (transformation/maturity/csf/digital-strategy)
  |   |   +-- credits.ts          # usacon credits
  |   |   +-- chat.ts             # usacon chat (message/history/delete, SSEストリーミング)
  |   |   +-- subsidy.ts          # usacon subsidy (search/show/favorite, SSEストリーミング)
  |   |   +-- job.ts              # usacon job (list/status/result)
  |   |   +-- report.ts           # usacon report (list/export/delete/weekly)
  |   |   +-- batch.ts            # usacon batch analyze (JSONL入力, dry-run)
  |   |   +-- export.ts           # usacon export (csv/xlsx)
  |   |   +-- settings.ts         # usacon settings (display/set)
  |   |   +-- strategy.ts         # usacon strategy (list/show/generate)
  |   |   +-- insights.ts         # usacon insights (list/show)
  |   |   +-- threads.ts          # usacon threads (list/pin/favorite)
  |   +-- session/
  |   |   +-- index.ts            # re-export
  |   |   +-- auth.ts             # Supabase認証（login/logout）
  |   |   +-- credentials.ts      # AES-256-GCM暗号化トークン管理
  |   |   +-- refresh.ts          # JWTトークンリフレッシュ
  |   +-- tui/
  |   |   +-- index.ts            # startTui() — 動的インポートでInk起動
  |   |   +-- App.tsx             # メインAppコンポーネント
  |   |   +-- Header.tsx          # ヘッダー表示
  |   |   +-- CompanySelector.tsx # 企業選択UI
  |   |   +-- MessageArea.tsx     # メッセージ表示
  |   |   +-- InputArea.tsx       # テキスト入力
  |   |   +-- StatusBar.tsx       # ステータスバー
  |   |   +-- reducer.ts          # useReducer アクション/リデューサー
  |   |   +-- types.ts            # TUI型定義
  |   +-- utils/
  |   |   +-- index.ts            # re-export
  |   |   +-- client.ts           # createAuthenticatedClient() + handleApiError()
  |   |   +-- output.ts           # カラー出力・JSON出力ユーティリティ
  |   |   +-- paths.ts            # ~/.usacon/ パス管理
  |   |   +-- activeJobs.ts       # SIGINT/SIGTERMグレースフルシャットダウン
  |   +-- __tests__/              # テストファイル（Vitest）
  +-- dist/                       # ビルド成果物
  +-- package.json
  +-- tsup.config.ts
  +-- tsconfig.json
  +-- README.md

開発時の注意事項

API応答のsnake_case/camelCase対応

APIレスポンスは snake_case（Supabaseカラム名そのまま）だが、app-coreの型定義は camelCase。 各コマンドでは mapXxx() 関数で明示的に変換している。

// credits.ts の例
function mapCreditBalance(raw: Record<string, unknown>): CreditBalance {
  return {
    creditsRemaining: (raw.credits_remaining ?? raw.creditsRemaining ?? 0) as number,
    // ...
  };
}

SSEストリーミング

chat.ts と subsidy.ts では、undici Pool を直接使用してSSEストリームを取得。 UsaconHttpClient はRaw ReadableStreamを公開しないため、直接undiciを使用する設計。

非TTY環境での動作

Claude Code の bash は非TTY → --json が自動適用される。 テキスト出力（テーブル形式、Markdown）のテストはユーザーが手動で実施する必要がある。

E2Eテスト基準

CLIパッケージの修正では npm run build && usacon <command> でのコマンド実行テストが本E2E。 ビルド成功だけでは不十分（E2E品質基準 Issue #1305-#1307教訓）。

ファイルサイズ制限

company import および batch analyze の入力ファイルは10MB上限。

CJSビルドでの import.meta 警告

tsupのCJS出力で import.meta に関する警告が出るが、機能影響なし（後日対応予定）。

日付表示

表示ヘルパーでは Asia/Tokyo タイムゾーンで日付をフォーマット。

テスト計画

包括的テスト計画（全140項目）は GitHub Issue #1399 に記載。 15セクション・6フェーズに分割され、Claude実施可能（約95件）とユーザー実施必須（約45件）に分類。

CLI実装の完了条件（必須）

CLI実装はコード修正だけで完了扱いにしない。以下のすべてを確認すること：

アンチパターン: コード修正 → npm run build 成功 → 完了とする（実機起動確認なし） → ビルド成功 ≠ 使える。必ずコマンドとして実行して動作確認すること。

セキュリティ改善ロードマップ

関連スキル

• usacon (~/.claude/skills/usacon/SKILL.md) — Webアプリ全体のガイド（本スキルはCLIパッケージに特化）
• issue-flow — GitHub Issue実装の自動ワークフロー
• issue-autopilot-batch — バッチIssue実装

改訂履歴

トラブルシューティング

CLI品質チェックリスト

• npm run build が全パッケージで成功するか
• usacon --version でバージョンが表示されるか
• 新規コマンドに --help テキストが設定されているか
• テスト（npm test）が全件パスするか
• TUIモードで新規メニュー項目が表示されるか