hub-creator

Hub Creator

ブランチ上で、新しい Datex Studio ハブ構成（configurationTypeId=2）を作成します。フィルターやグループ化オプションを備えたトップレベルの UI コンテナー、グリッド／エディター／フォーム／カスタム Angular コンポーネントをマウントするタブ、ツールバーボタン、クリックフローを設定します。

関連項目： hub-editor — ブランチ上で既存ハブのツールバー／フローを変更します（このスキルは新しいハブを作成するためのものです）。

References

• ../datex-studio-shared/branch-setup.md — ブランチ／接続の選択（各スキルで共通）
• references/hubs.md — ハブ作成に関する信頼できるリファレンス：ファイル形式、ランタイムグローバル、呼び出しコントラクト、一般的なパターン、事前チェックリスト
• ../datex-studio-conventions/file-format.md — configurationTypeId の表と TypeScript 式のエンコード規則
• ../datex-studio-conventions/naming-conventions.md — _hub サフィックス、ファイル名の一致、表示名の規則
• ../datex-studio-runtime/runtime-globals.md — ハブコードで利用できるプラットフォーム注入のグローバル変数（$flows、$shell、$utils、...）
• ../datex-studio-runtime/calling-conventions.md — UI 層の呼び出し規則（関数を呼び出し、アクションは呼び出さない。ダイアログは $shell 経由で開く）
• ../component-wiring-check/references/component-wiring.md — ホスト参照のコントラクト、vars 宣言必須の規則、moduleId の規則

Dependencies

• requirements-gathering スキル — 会話コンテキストに要件概要がまだ存在しない場合、その作成のために呼び出します
• grid-creator／selector-creator／form-creator／editor-creator スキル — ハブから参照されるタブグリッド、フィルター用セレクター、ダイアログフォーム／エディターがブランチ上にまだ存在しない場合に呼び出します
• component-wiring-check スキル — プッシュ前に、configParameters とターゲットの inParams のコントラクトを監査するために呼び出します（配線漏れの落とし穴）

CLI Lifecycle

ハブの作成では、すべてのプラットフォーム構成タイプに対応する汎用 CRUD プリミティブである dxs configuration を使用します。dxs hub サブコマンドやフィールド単位のパッチ適用はありません。JSON 本文全体を作成する（または取得して抽出する）必要があり、編集後に全体をプッシュし直します。

新しいハブを作成する：

# 1. Build body.json from scratch (see references/hubs.md → Minimal Valid Skeleton)
# 2. Validate — gates the push. Exit 1 = errors found (read validation_errors, fix, re-run), not a broken CLI
dxs configuration validate hub -b <branchId> -D body.json
# 3. Create
dxs configuration upsert hub -b <branchId> -D body.json

既存のハブを編集する（作成中に範囲が「新規」から「変更」に広がった場合のみ）：

# 1. Fetch — note the envelope wrapper
dxs configuration get hub <configId> -b <branchId> -O envelope.json
# 2. EXTRACT THE INNER BODY (round-trip footgun guard — see "Round-trip rule" below)
jq .json envelope.json > body.json
# 3. Edit body.json
# 4. Validate — gates the push. Exit 1 = errors found (read validation_errors, fix, re-run), not a broken CLI
dxs configuration validate hub -b <branchId> -D body.json
# 5. Push
dxs configuration upsert hub -b <branchId> -D body.json

既存ハブのツールバー／フローだけを変更するワークフローの場合は、ここで止めて hub-editor スキルに切り替えてください。ツールバー／クリックフローの編集パターンと、ロールによるアクセス制御のレシピが含まれています。

Round-trip rule (critical)

既存の構成を編集する際は、envelope.json を直接 dxs configuration upsert にパイプしてはいけません。構成内容が気付かないうちに破壊されます。上記の修正済み手順（編集前に jq で内部の .json を抽出する方法）は、ラウンドトリップのたびに必須です。正式なラウンドトリップ手順と根本的なバグについては、../datex-studio-shared/configuration-roundtrip.md を参照してください。

Workflow

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch/connection selection
        |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO -> invoke `requirements-gathering`
  |            |
  +-----+------+
        |
[Phase 2: Author hub body]
Decide what the hub IS:
  - which filters scope the experience
  - which tabs (grids / other components) mount inside it
  - role-gating, on_init access guard, hub-local flows
Consult references/hubs.md for file shape, $hub runtime,
required top-level fields, common patterns
        |
[Phase 3: Wire toolbar / flows]
Toolbar buttons + click flows; dialog openers via $shell
Audit dead-wiring trap (hub filter -> tab configParameters
-> grid inParams MUST stay in sync) — invoke
`component-wiring-check` if mounted grids/selectors
need extension
        |
[Phase 4: Validate + push]
dxs configuration validate hub -b <branchId> -D body.json
        |
   +----+----+
   |         |
  CREATE   MODIFY-EXISTING
   |         |
   |         use the corrected round-trip
   |         (get -O envelope -> jq .json -> body)
   |         |
   +----+----+
        |
        v
dxs configuration upsert hub -b <branchId> -D body.json
   (upsert creates or updates by referenceName — one command for both)
        |
[Phase 5: Verify in Studio (optional)]
Reload the hub in the running app; confirm filters render,
tabs query, toolbar buttons fire
        |
[invoke `post-edit-verification`; then `component-validator`]

Phase Details

Phase 1: Setup + Requirements

1. ブランチと接続の選択については、../datex-studio-shared/branch-setup.md に従ってください。ブランチ ID を決めつけてはいけません。ユーザーに確認してください。
2. 会話コンテキストに要件概要がすでに存在するか確認します（requirements-gathering または別の呼び出し元スキルが作成したもの）。
   • 概要がある — それを使用します。概要にはハブの目的、ユーザーに必要な絞り込みフィルター、内部にマウントするタブ／グリッド、ロールによるアクセス制御のルール、ツールバーのアクションが記載されています。
   • 概要がない — まず requirements-gathering スキルを呼び出します。ハブはトップレベルのエントリーポイントです。最初にフィルターセットとタブのレイアウトを適切に決めておけば、手戻りを減らせます。

フェーズ 2：ハブ本体を作成する

まずハブの役割を決めてから、body.json を作成します。

1. ファイルの基本事項。 以下の事前チェックリストと ../datex-studio-conventions/universal-checklist.md に従います。-hub.json ファイルの形式については、references/hubs.md → ファイルの配置と命名 を参照してください。
2. フィルター。 各フィルターフィールドの configId / moduleId は、実在するセレクター（*-selector.json）を参照している必要があります。セレクターがまだブランチに存在しない場合は、まず selector-creator を呼び出してください。セレクターの各 configParameter に対して、フィルターの dropdownConfig.configParameters に項目を用意します（該当しない項目には value: "" を指定します）。
3. タブ。 各タブで、ブランチ上のグリッド（または他のコンポーネント）を指す contentConfig を宣言します。対象のグリッドがまだ存在しない場合は、まず grid-creator を呼び出してください。タブの configParameters 配列は、対象の inParams と完全に一致させてください。フェーズ 3 の未接続チェックを参照してください。
4. vars 配列。 ハブのフローコード内で使用されるすべての $hub.vars.<id> を、トップレベルの vars 配列で宣言する必要があります。references/hubs.md → ランタイムグローバル および ../component-wiring-check/references/component-wiring.md を参照してください。
5. onInitFlowConfig。 初期フィルターのデフォルト設定、コンテキストの読み込み、アクセス制御を行うハブパターン（権限チェック → 拒否時に $hub.close()）でよく使用されます。references/hubs.md → 一般的なパターン を参照してください。
6. TypeScript 式のエンコード。 hubTitle、hubDescription、およびすべての value / tooltip / placeholder / label は、3 種類のエンコード規則に従います。表示テキストはバッククォートで囲みます："`Widget overview`"。../datex-studio-conventions/file-format.md → 宣言的な文字列値は TypeScript 式 を参照してください。

フェーズ 3：ツールバーとフローを接続する

1. ツールバーボタンとクリックフロー。 各ツールバーボタンのエントリーには、ハブ内のフローまたは外部関数を指す clickFlowConfig があります。ハブのコードから関数を呼び出すには $flows.<Package>.<fn> を使い、フォーム／エディターを開くには $shell.<Package>.open<referenceName>Dialog(...) を使います。アクションを直接呼び出してはいけません。アクションは関数でラップしてください。エンジン切り替え、オプション設定ダイアログ、アクセス制御付き on_init、共有ローカルフローのパターンについては、../datex-studio-runtime/calling-conventions.md と references/hubs.md → Common Patterns を参照してください。

2. 配線漏れの落とし穴を監査する。 ハブで最もよくあるバグは、ハブフィルターがタブの configParameters にバインドされていても、マウントされたグリッドがその ID を inParam として宣言していないことです。バインドされているように見えても、グリッドには値が渡されません。

   ルール：タブの configParameters 内のすべてのバインドは、マウントされたグリッドの inParams に名前が定義されている必要があります。また、グリッドが宣言するすべての inParam には、タブの configParameters にエントリーが必要です（未使用のエントリーには value: "" または value: null を指定します）。

   特定のタブのグリッドの対象を絞り込むハブフィルターがある場合（たとえば、projects フィルターで project_ids によってルールグリッドを絞り込む場合や、contract フィルターで contract_id によってドキュメントグリッドを絞り込む場合）、同じ編集でマウントされたグリッドの最上位の inParams を監査してください。バインドが必要なのに、グリッドに一致する inParam が宣言されていない場合は、同じ編集でグリッドを拡張してください（グリッドフローはデータソース呼び出しの構築時に $grid.inParams.<id> を読み取るため、基盤となるデータソースも拡張します）。

   プッシュする前に component-wiring-check を実行し、moduleId、configParameters のミラー、宣言された vars など、参照契約全体を監査してください。references/hubs.md → Invocation Contract と ../component-wiring-check/references/component-wiring.md を参照してください。

3. ツールバー／タブの ID はハブ内で一意にしてください。 フローコードは id で参照します（$hub.toolbar.save.control...、$hub.tabs.rules.hidden = ...）。重複すると、警告なしに上書きされます。

フェーズ 4：検証してプッシュする

# Validate the body locally against the branch. Exit 1 = validation found errors
# (read validation_errors, fix body.json, re-run) — not a broken CLI. Do not push on exit 1.
dxs configuration validate hub -b <branchId> -D body.json

# For a new hub
dxs configuration upsert hub -b <branchId> -D body.json

# For modify-existing (round-trip — never skip the jq extract)
dxs configuration get hub <configId> -b <branchId> -O envelope.json
jq .json envelope.json > body.json
# ... edit body.json ...
dxs configuration upsert hub -b <branchId> -D body.json

検証では、必須フィールドの欠落、不正な configParameters の形式、セレクター／グリッドの参照エラーがプッシュ前に明らかになります。配線漏れの落とし穴（マウントされたグリッドの inParams に id が存在しない configParameters）は検出されません。これはコンポーネント間の契約に関する問題であり、component-wiring-check と上記のフェーズ 3 のルールを使って監査してください。

フェーズ 5：Studio で確認する（任意）

実行中のアプリでハブを再読み込みします。

• フィルターが表示され、ドロップダウンに値が入力されること（セレクターが正しく接続されていること）。
• フィルターを変更するとタブがクエリを実行すること（タブの configParameters とグリッドの inParams の契約が保たれていること）。
• ツールバーボタンがクリックフローを実行し、ダイアログを開く処理が戻り、$hub.refresh() が状態を反映すること。
• 権限のないユーザーには、ロールで制御されたタブが非表示になること（アクセス制御付き on_init フローが実行されること）。

実行中のアプリを利用できない場合は、設定を再取得し、修正済みの jq .json 抽出パターンを使って body.json と差分を比較し、プッシュが反映されたことを確認してください。

事前チェックリスト

プッシュする前に、references/hubs.md → 事前チェックリストの全項目を確認してください。簡易版は次のとおりです。

1. ファイルの基本事項：configurationTypeId: 2、referenceName の末尾が _hub — さらに共通チェック（../datex-studio-conventions/universal-checklist.md）。
2. タブには完全な configParameters コントラクトを指定します（マウントされたグリッドの inParams と正確に一致させます。余分な項目も不足も認められません）。
3. フィルターバインディングをコントラクトに完全に準拠させます（セレクター参照が解決され、各セレクターの configParameter にエントリーがあります）。
4. 変数を宣言します（フローコード内のすべての $hub.vars.<id> をトップレベルの vars に含めます）。
5. 呼び出し階層に準拠します（関数は $flows.<Package>.<fn> 経由で呼び出し、ダイアログを開く場合は $shell.<Package>.open<referenceName>Dialog(...) を使用し、アクションを直接呼び出さないでください）。
6. ツールバー ID とタブ ID はハブ内で一意にします。
7. TypeScript 式の文字列を正しくラップし、動的なツールチップは宣言済みの $hub.vars.<name> 経由で設定します。

よくある間違い

間違い	修正方法
タブの configParameters が、グリッドで inParam として宣言されていない ID にバインドしている	接続が機能せず、値は暗黙に破棄されます。バインディングを削除するか、同じ編集でグリッドの inParams と基盤となるデータソースを拡張してください。フェーズ 3 を参照してください。
dxs configuration get -O envelope.json の出力を直接 dxs configuration upsert -D envelope.json に渡す	設定内容が暗黙に破損します。編集する前に、必ず jq .json envelope.json > body.json を実行してください。上記の「ラウンドトリップのルール」を参照してください。
トップレベルの vars 配列で <id> を宣言せず、フローコードに $hub.vars.<id> = ... と記述する	変数が未宣言のため、書き込みが暗黙に失敗するか、実行時エラーになります。すべての変数を宣言してください。
ハブコードからアクションを直接呼び出す（$flows.<Package>.<action_name>(...)）	UI 階層のルールにより、呼び出せるのは関数だけです。アクションを関数でラップしてください。../datex-studio-runtime/calling-conventions.md を参照してください。
フローコードからフィルターまたはツールバーボタンの .control.tooltip に代入する	動的なツールチップには何も反映されません。代わりに、宣言済みの $hub.vars.<name> にバインドする必要があります。references/hubs.md → 事前チェックリストの項目 7 を参照してください。
description が 100 文字を超えている	SQL 列の上限により、プッシュ時の検証に失敗します。短くしてください。
referenceName が _hub で終わっていない、またはファイル名のベース部分と一致しない	インポート／検索が機能しなくなります。スネークケースにし、末尾を _hub にして、ファイル名のベース部分と一致させてください。
タブの moduleId に、マウントされたグリッドではなくハブのパッケージを設定している	コンポーネント間参照のルールに違反します。moduleId には必ず対象のパッケージを指定してください。../component-wiring-check/references/component-wiring.md を参照してください。
2 つのツールバーボタン（または 2 つのタブ）で同じ id を使用している	暗黙に上書きされ、フローコードからはどちらか一方しか参照できません。ハブ内で ID を一意にしてください。

編集後、post-edit-verification を実行して、description／JSON／スキーマの違反を検出してください。最終確認には component-validator を実行してください。