olares-shared

olares-cli 共通ルール

ランタイムスキルを使う前に、この簡潔な入口をお読みください。ここでは、アクティブプロファイルのモデル、プラットフォームのエントリーポイント、認証時に続行するか停止するかのルールを説明します。タスクがどのスキルに属するか分かった後に必要となる情報です。詳細なリファレンスは、現在のタスクに該当する場合にのみ読み込んでください。

• スイートマップ：各タスクを担当するスキルと、olares-cli が PATH にない場合のインストール方法を説明します。タスクがまだスキルに振り分けられていない場合にお読みください。すでに振り分け済みのタスクでは、再度読む必要はありません。

出力の読み方

プロファイルを使用するすべてのコマンドツリーでは、機械可読な出力を -o json で指定します（--json も同じ指定で、古いスクリプトとの互換性のために残されています）。この指定で動詞の実行に失敗すると、stderr に {"error":{"code","message","retryable","action"}} が出力され、stderr にはそれ以外の内容が含まれないため、そのまま全体を解析できます。

.error.code が設定されている場合は、その値に基づいて処理を分岐するのが有効です。現時点では、他のすべての失敗とは異なる復旧方法が必要な次の失敗で設定されます：auth_no_profile、auth_not_logged_in、auth_token_expired、auth_token_invalidated、timeout と、Router が上流から報告する内容です。それ以外は、詳細全体が .message に格納された unclassified として返されます。そのため、まずコードを確認し、コードがないことを何か特定の意味だと決めつけず、メッセージを確認してください。retryable と action は、失敗の種類から判明している場合にのみ含まれます。含まれていない場合は「いいえ」ではなく「不明」を意味します。

一部のコマンドツリーでは、独自の結果ドキュメントも返されます（Market のライフサイクル動詞では .status と .finalState が報告されます）。その場合は、そちらを確認してください。

プラットフォームのエントリーポイント

• Olares プラットフォームモデル：ユーザー空間のストレージ、uid/gid 1000、保護された Home ディレクトリ、アプリ／名前空間のネットワーク、システムミドルウェア、Olares のバージョンの意味を説明します。これらの概念に関係するファイル、チャート、クラスター、設定のタスクでお読みください。
• アプリケーションの状態遷移：ライフサイクルの遷移、許可される操作、バックエンドのタイムアウト、ダウンロードの直列化、running の意味、信頼できない進捗状況について説明します。Market の操作やランタイムの診断でお読みください。
• プロファイルと認証：ログイン／インポートのフロー、プロファイルの状態、トークンの保存と更新の動作を説明します。プロファイルの操作や認証からの復旧にのみお読みください。

アクティブプロファイル

1つのプロファイルで、1つの Olares インスタンスと1つの Olares ID が選択されます。プロファイルを使用するすべてのコマンドは、その選択先を対象とし、コマンドごとの --profile オーバーライドはありません。

コマンド	目的
olares-cli profile list	プロファイル、現在の選択、認証状態、キャッシュされた Olares バージョンを表示します
olares-cli profile whoami	選択中のプロファイルの ID とロールを表示します。他のスキルが判定に使う admin／normal の回答も表示します
olares-cli profile use <name|->	選択先を切り替えます。- を指定すると、前のプロファイルに戻ります
olares-cli profile login	パスワードと任意の TOTP を使って認証します
olares-cli profile import	リフレッシュトークンを使って初期設定します
olares-cli profile remove <name>	プロファイルとその認証情報を削除します

フラグについては olares-cli profile --help を、ログインや復旧については認証リファレンスを確認してください。

認証準備状況の確認

デフォルトでは次のように進めます。

• logged-in、expired、pending の場合は続行します。期限切れのアクセストークンは通常、次のリクエストで更新されます。また、pending はプラットフォームが発行したプロファイルで、付与された権限がまだ交換されていない状態です。
• never と invalidated の場合は、profile login または profile import を停止します。ただし、SOURCE が platform(<app>) を読み込む場合は例外です。これはアプリケーションに対してプラットフォームが発行したものであり、その場合、login、import、remove はすべて拒否されます。この権限をローカルで発行または取り消す方法はなく、アプリケーションを再インストールするか修復する必要があります。アプリケーションコンテナ内にプロファイルがまったくない場合も同様に対応し、ログインを求めず、アプリケーションの修復が必要だと伝えます。
• unknown または解析できないトークンの場合は、推測せずに業務コマンドを実行し、型付きエラーに応じて対応します。

すべてのコマンドで事前確認を行わないでください。CLI は認証拒否を受けるとトークンを更新し、1 回だけ再試行します。CLI が認証情報の欠落または無効化を明示した場合、あるいは 401／459 が継続した後にログイン操作を表示した場合は、ログインを停止します。403 による権限拒否、ネットワークエラー、5xx はログインが必要であることを示すものではありません。認証エラーに対する再試行ループは決して作らないでください。

安全性とエスカレーション

• 決してパスワードをコマンドの引数に含めないでください。対話型プロンプトまたは --password-stdin を使用してください。
• 決してアクセストークンやリフレッシュトークンを表示しないでください。インポート元には、シークレット環境変数またはシークレットマネージャーを使用してください。
• ログイン、認証情報の置き換え、対象が曖昧な場合、またはユーザーが許可したタスクの範囲外の操作を行う前に、確認してください。
• 許可されたチャートのデプロイ／デバッグタスクの範囲内では、インストール、アップグレード、再起動、アンインストール、クリーン再インストールは通常の反復作業の手順です。コマンドごとに再確認する必要はありません。