@takagaki/cortex-decisions-viewer 0.4.78 → 0.4.80

package/dist/render.js

@@ -356,6 +356,20 @@ function capabilityState(cap, ctx) {
     // 途中で壊れたデータで**画面が落ちない**ようにするためだけ——実体（同期ソースの行・
     // ライブ参照）だけで判定し、無ければ「まだ繋がっていない」側へ倒す。
     // **ここに宣言を読む道を足さないこと。** 足した瞬間、実態と食い違える経路が復活する。
+    // **fleet のデータが1枚も無いときは「未接続」（#138）。** 下の判定は
+    // 「行が無い＝使っていない」と読んで `off`（未使用）を返すが、立ち上げ直後の案件は
+    // まだ夜間バッチが一度も走っていないだけで、何も決めていない。6つの能力に
+    // 「未使用」が並ぶと、**繋ぐ入口を出すという目的と逆のことを画面が言う**
+    // （「使わないことになっている」と読める）。
+    //
+    // **分岐は「1つも無い」に限る。** この防御経路は取得に失敗したときにも通るので、
+    // 判定材料が1つでもあるなら従来どおり——失敗を「未接続」に塗り替えない。
+    if (ctx.internals.length === 0 &&
+        ctx.externals.length === 0 &&
+        ctx.pipes.length === 0 &&
+        Object.keys(ctx.capabilities || {}).length === 0) {
+        return "idle";
+    }
     const used = (internal != null && internal.enabled !== false) ||
         (isLive && liveExts.length > 0);
     const off = (internal != null && internal.enabled === false) || !used;
@@ -429,11 +443,17 @@ function renderConnectionMap(site) {
     const externals = site.externalSources ?? [];
     const pipes = site.pipelines ?? [];
     const caps = site.capabilities ?? {};
-    // **fleet のデータが1つでも取れているか、だけで判定する（#125②）。**
-    // 素の Decisions ビュー（fleet-status.json が無い構成）ではマップを出さない現行の意図は
-    // そのまま。宣言（`tools`）は条件から外した（⑤）——艦隊の fleet-status.json は
+    // **「この画面から接続できる構成か」で判定する（#138）。**
+    // 素の Decisions ビュー（投入フォームを持たない構成）ではマップを出さない現行の意図は
+    // そのまま。宣言（`tools`）は条件から外してある（#125⑤）——艦隊の fleet-status.json は
     // すべて capabilities を持つので、宣言はもうマップの有無を左右しない。
-    if (!internals.length && !externals.length && !pipes.length && !Object.keys(caps).length) {
+    //
+    // **中身が空でも、intake があるならマップを出す。** 立ち上げ直後の案件は fleet の
+    // データが丸ごと無いが、そこは**まさにこれから繋ぐ案件**で、6つの能力とその入口を
+    // 一望できる図が一番要る場面だった。中身の有無で消していたので、新規案件の画面からは
+    // 「何を繋げばよいのか」を示すものが消えていた。
+    if (!site.intake &&
+        !internals.length && !externals.length && !pipes.length && !Object.keys(caps).length) {
         return null;
     }
     const hasCaps = Object.keys(caps).length > 0;
@@ -2077,6 +2097,18 @@ ${capabilityState.toString()}
     return row;
   }
 
+  /**
+   * GitHub App のインストール先（#138）。
+   *
+   * **1箇所に持つ。** 組織ごとの行と、読み取りトークンのカードの両方から出すので、
+   * 書き写すと片方だけが古くなる。
+   *
+   * **文書化されている形だけを使う。** target_id に組織のログイン名を渡す形は GitHub の
+   * 文書に無く、未ログインだとログイン画面へ転送されて 200 が返るので、効いているかを
+   * 外から確かめられない。**確かめられないものを顧客に押させない。**
+   */
+  var GITHUB_APP_INSTALL_URL = "https://github.com/apps/classmethod-cortex-app/installations/new";
+
   /**
    * 接続状況のライブ値（op=state の応答）。取得前・取得失敗時は null。
    *
@@ -2218,6 +2250,9 @@ ${capabilityState.toString()}
     // 「これから繋げる入口」も接続マップのアンカーの受け皿も無くなる。
     // 何を繋げるかは製品が決めていて、案件データでは変わらない（#125②）。
     var CAP_ORDER = ["課題管理", "会議", "共有資料", "チャット", "デザイン", "開発"];
+    // internalSources に行が来る能力（チャットと開発は externalSources 側にしか来ない）。
+    // **fleet-status.json がまだ無い案件のために、行が無くても設定を出す**判定に使う（#138）
+    var CAP_INTERNAL = ["課題管理", "会議", "共有資料", "デザイン"];
     var capBox = {};
     var manualBox = {};
     // 対応表は externalCapability が持つ（状態判定・件数の集計と同じものを使う）
@@ -2334,6 +2369,26 @@ ${capabilityState.toString()}
       });
     }
 
+    // **行が1つも無い能力にも、設定の口を出す（#138）。**
+    //
+    // 実機で踏んだ欠陥の本体はここだった。各能力の設定UI一式は internalControls の中に
+    // あり、その呼び出しは上の internals.forEach の内側だけ。行を作っているのは夜間バッチ
+    // （fleet-status.json）なので、**立ち上げ直後の案件には1行も無く、タイルを開いても
+    // 「この能力にはまだ設定できるものがありません。」で終わる**——接続先のフォームを
+    // 出す・出さないの判定を直しても、その手前で画面に到達できていなかった。
+    //
+    // **データの行（カード）は作らない。** 作れば、読めていない件数・最終同期・ラベルを
+    // 画面が装うことになる。ここで足すのは操作だけで、状態の表示はタイルとマップが持つ。
+    //
+    // 状態が分からないと出せない操作（会議・共有資料のトグルや追加フォーム）は
+    // internalControls 側の判断で従来どおり出ない——不明な状態に操作を出さない原則は
+    // 変えていない。ここが変えるのは「呼ばれもしなかった」ことだけ。
+    CAP_INTERNAL.forEach(function (cap) {
+      if (internals.filter(function (s) { return s.kind === cap; }).length) return;
+      var ctl = internalControls({ kind: cap }, false);
+      if (ctl) pushCap(cap, ctl);
+    });
+
     if (sources.length) {
       // **見出しは付けない。** #101 で行は能力ごとのモーダルへ移ったので、
       // ここに見出しを置くと中身ゼロの見出しが節の先頭に立つ（実際に8案件すべてで出ていた）
@@ -2427,12 +2482,9 @@ ${capabilityState.toString()}
         if (!ok && !unsure) {
           row.appendChild(el("a", {
             class: "ds-owner-install",
-            // **文書化されている形だけを使う。** target_id に組織のログイン名を渡す形は
-            // GitHub の文書に無く（GitHub自身のUIは数値のアカウントIDを入れる）、
-            // 未ログインだとログイン画面へ転送されて 200 が返るので、
-            // 効いているかを外から確かめられない。**確かめられないものを顧客に押させない。**
-            // どの組織かはこの行に出ているので、選ばせる形で足りる
-            href: "https://github.com/apps/classmethod-cortex-app/installations/new",
+            // どの組織かはこの行に出ているので、選ばせる形で足りる（URLの形は
+            // GITHUB_APP_INSTALL_URL のコメントを参照）
+            href: GITHUB_APP_INSTALL_URL,
             target: "_blank", rel: "noopener",
             text: "この組織にインストール →",
           }));
@@ -2440,6 +2492,24 @@ ${capabilityState.toString()}
         obox.appendChild(row);
       });
       pushCap("開発", obox);
+    } else {
+      // **組織が1件も無い案件にも、App の入口を置く（#138）。**
+      // githubOwners は夜間バッチの成果物なので、立ち上げ直後の案件には無い。
+      // インストールの導線を「未接続の組織の行」の中にしか置いていなかったため、
+      // **まだ何も繋いでいない案件＝一番 App を入れてほしい案件**の画面に、
+      // App へ行く道が1本も無かった（実機で踏んだ）。
+      var obox0 = el("div", { class: "ds-owners" });
+      obox0.appendChild(el("div", { class: "ds-sub", text: "組織ごとの接続状況" }));
+      obox0.appendChild(el("div", { class: "ds-owner" }, [
+        el("span", { class: "ds-owner-state ds-gate-idle", text: "⦿ 未接続　読み取っている組織はまだありません" }),
+        el("a", {
+          class: "ds-owner-install",
+          href: GITHUB_APP_INSTALL_URL,
+          target: "_blank", rel: "noopener",
+          text: "組織に GitHub App をインストール →",
+        }),
+      ]));
+      pushCap("開発", obox0);
     }
 
     pushCap("開発", adders.querySelector('[data-adder="github"]'));
@@ -2458,10 +2528,19 @@ ${capabilityState.toString()}
      *
      * **unknown（確かめられなかった組織）も「要る」側に倒す。** 実態は none かもしれず、
      * 隠す方に倒すと直せなくなる（画面には組織ごとに「確認できませんでした」と出ている）。
+     *
+     * **「無い」と「空」は別物（#138・オーナー判断 2026-08-18）。**
+     *   - 値そのものが来ていない（undefined）… fleet-status.json をまだ持っていない、または
+     *     取得に失敗した。**情報が無いので出す**（上の #118 の意図はここが担う）。
+     *   - 空の配列（[]）… 夜間バッチは走ったが、読み取り対象の開発リポジトリが0件。
+     *     読むものが無いのだから鍵も要らない。**出さない**。
+     * 以前はどちらも空配列に丸めていたので、0件の案件にも欄が出続けていた。
+     * **この2つを混ぜると #118 を壊す**（立ち上げ直後の案件から唯一の入口が消える）。
      */
     function githubTokenNeeded() {
-      var list = fleetVal("githubOwners") || [];
-      if (!list.length) return true;
+      var list = fleetVal("githubOwners");
+      if (!Array.isArray(list)) return true;
+      if (!list.length) return false;
       return list.some(function (o) { return !o || (o.source !== "app" && o.source !== "token"); });
     }
 
@@ -2472,9 +2551,16 @@ ${capabilityState.toString()}
       // 全組織が繋がっているなら、入力欄ではなく**そう言う1行**に畳む（#118）。
       // 何も出さないと「トークンはどこで入れるのか」が分からなくなる
       if (k === "external-sources" && !githubTokenNeeded()) {
+        // **0件の案件に「すべての組織に接続済み」と言わない（#138）。** 組織が1つも無いのに
+        // 接続済みと書けば嘘になる。畳む理由が違うので、文も分ける——次の一歩
+        //（リポジトリを登録する）が同じモーダルの上にあることまで書く
+        var ownersNow = fleetVal("githubOwners");
+        var noRepos = Array.isArray(ownersNow) && ownersNow.length === 0;
         pushCap(SECRET_CAP[k], el("p", {
           class: "sec-how ds-all-connected",
-          text: "すべての組織に接続済みです（GitHub App / 登録済みトークン）。読み取りトークンの登録は要りません。",
+          text: noRepos
+            ? "読み取り対象の開発リポジトリがまだありません。このモーダルの上にあるリポジトリの追加フォームで登録すると、トークンが要るかどうかをここに出します。"
+            : "すべての組織に接続済みです（GitHub App / 登録済みトークン）。読み取りトークンの登録は要りません。",
         }));
         return;
       }
@@ -2980,6 +3066,47 @@ ${capabilityState.toString()}
   var TARGETS_RACE_NOTE =
     "他の人が先に接続先を変更しました。最新の一覧に更新しましたので、内容を確かめてもう一度お試しください。";
 
+  /**
+   * この画面から Backlog の接続先を足したり外したりできるか（#138）。
+   *
+   * **同期ミラー（s.url）では判定しない。** 以前は「一度でも同期していれば書き込み先が
+   * 決まる」として s.url を見ていたが、正本（issues-config.json）は雛形から作られるので
+   * 立ち上げ直後の案件にも実在する。ミラーで判定すると、**まだ一度も繋いでいない案件＝
+   * これから繋ぎたい案件**だけがフォームを出せない（実機で踏んだ）。
+   *
+   * 出さないのは、この画面からの投入に対応していない固定IP同期の案件だけ。
+   * **その見分けは SITE.secretKinds に backlog が入っているかで行う。**
+   * 固定IPかどうかを直接示す値は画面に来ておらず（インフラ側の設定にしか無い）、
+   * 鍵の欄を出すかどうかの判定が同じ線で引かれているので、代理として正確に使える。
+   * インフラ側で secretKinds の条件を変えるときは、**ここの意味も一緒に変わる**。
+   */
+  function backlogTargetsEditable() {
+    return (SITE.secretKinds || []).indexOf("backlog") >= 0;
+  }
+
+  /**
+   * Backlog のAPIキーを、どのスペースの棚へ入れるか（#138）。
+   *
+   * **名簿（config.ts）の backlogSpace に頼らない。** 立ち上げ直後の案件は接続先を
+   * まだ名簿に書いていないので、サーバ側だけではスペースが決まらない——鍵の欄を出しても
+   * 保存が断られる（#127 で「2つ目以降のスペースの鍵は画面から名乗ってもらう」経路が
+   * 用意してあるので、そこへ載せる）。
+   *
+   * **名乗るのは1つに定まるときだけ。** 画面の接続先が複数のスペースにまたがっているなら、
+   * どちらの鍵として入れたのかは入れた人にしか分からない。勝手に片方を選ぶと、
+   * **読み手が見に行くのと別の棚へ黙って入る**（入れたのに動かない、が一番起きてほしくない形）。
+   * 名乗らなければサーバが従来どおり名簿の値を使う。
+   */
+  function backlogSecretSpace() {
+    var list = backlogTargetsNow(null);
+    var domains = [];
+    for (var i = 0; i < list.length; i++) {
+      var d = String(list[i].domain || "").toLowerCase();
+      if (d && domains.indexOf(d) === -1) domains.push(d);
+    }
+    return domains.length === 1 ? domains[0] : "";
+  }
+
   /**
    * 「課題管理」カードの接続先（一覧＋追加＋削除・#127）。
    *
@@ -2993,9 +3120,7 @@ ${capabilityState.toString()}
    */
   function backlogTargetsSection(s) {
     var targets = backlogTargetsNow(s);
-    // 書き込み先（正本の置き場）が決まらない案件では操作を出さない。判定は呼び出し側と
-    // 同じ s.url（同期ミラーが1つでもあるか）で、フォームを出さない条件と揃える
-    var editable = !!(s && s.url);
+    var editable = backlogTargetsEditable();
 
     var listEl = el("div", { class: "ds-target-list" });
     var current = el("div", { class: "ds-current" }, [
@@ -3195,12 +3320,13 @@ ${capabilityState.toString()}
       // 伝えてフォームを出さない形なので、課題管理だけ不揃いだった。
       // 一覧そのもの（現在の接続先）は**そういう案件にも出す**——読めているものを隠さない
       //
-      // **接続先の正本は issues-config.json（#111）**だが、その置き場は
-      // 同期ミラー（backlog-settings.json）の位置から決めている。ミラーが1つも
-      // 無い案件では正本をどこへ置けばよいかも決められないので、条件は変わらない
+      // **判定は「同期したことがあるか」ではなく「この画面から投入できる案件か」（#138）。**
+      // 接続先の正本（issues-config.json）は雛形から作られるので、立ち上げ直後の案件にも
+      // 実在する。同期ミラーの有無で門前払いすると、**新規案件がこの画面から
+      // Backlog に繋げない**——設定UIを置いている意味が無くなる
       box.appendChild(backlogTargetsSection(s));
-      if (!s.url) {
-        box.appendChild(el("p", { class: "sec-how", text: "この案件はまだ一度も Backlog と同期していないため、この画面からは接続先を設定できません。先に初回の同期を実行するか、cortex の担当者にご連絡ください。" }));
+      if (!backlogTargetsEditable()) {
+        box.appendChild(el("p", { class: "sec-how", text: "この案件の Backlog は別の経路で同期しているため、この画面からは接続先を変更できません。変更が必要なときは cortex の担当者にご連絡ください。" }));
         used = true;
       }
       // **接続先の下に置く。** リアルタイム同期は「どのプロジェクトを見るか」が
@@ -4372,8 +4498,19 @@ ${capabilityState.toString()}
     "figma": {
       icon: "🎨",
       title: "Figma のトークン",
-      desc: "デザインの画面インベントリを毎晩同期するために使います。",
-      how: "Figma → Settings → Security → Personal access tokens で発行（file_content:read があれば足ります）",
+      desc: "デザインの画面インベントリと、Figma に付いたコメント（指摘）を毎晩同期するために使います。",
+      // **必要なスコープは実装が叩くAPIから決まる。** sync-designs は
+      //   GET /v1/files/{key}          → file_content:read（画面インベントリ）
+      //   GET /v1/files/{key}/comments → file_comments:read（指摘の同期）
+      // の2本だけを呼ぶ。**片方だけだと、もう片方が静かに入ってこない**——
+      // 特に file_comments:read の欠落は「同期は緑なのに指摘だけ増えない」という
+      // 気づきにくい壊れ方をする（コメント同期は後から足した機能で、この案内が追随していなかった）。
+      // 書き込み権限は1つも要らない。files:read（非推奨・広範）は選ばせないこと。
+      how: "Figma → Settings → Security → Personal access tokens で発行。スコープは file_content:read と file_comments:read の2つにチェックを入れてください（どちらも読み取りのみ・書き込み権限は要りません）",
+      // **スコープが正しくても、招待が無いと読めない。** トークンは「そのアカウントが
+      // 見られるファイル」しか読めないので、招待漏れは 404 になる。権限の問題に見えないため
+      // 現場で切り分けに時間がかかる（実際に踏んだ）。入力欄の隣に書いておく。
+      note: "発行したアカウントを、対象の Figma ファイルに閲覧者として招待しておいてください（招待が無いとトークンが正しくても読めません）。",
     },
     "backlog": {
       icon: "📋",
@@ -4399,7 +4536,16 @@ ${capabilityState.toString()}
       icon: "🐙",
       title: "GitHub の読み取りトークン",
       desc: "開発リポジトリの Issues / Discussions を読み、Gold の原料にするために使います。",
-      how: "GitHub → Settings → Developer settings → Personal access tokens で、対象リポジトリに Contents / Issues の Read-only を付けて発行",
+      // **第一の案内は GitHub App（#138）。** 実装の本線は App のインストールトークンで、
+      // 個人トークンは App を入れられない組織のフォールバックでしかない（既存案件は
+      // すでに App で読めている）。画面が個人トークンを勧め続けると、発行と入れ直しが
+      // 要る側に人が流れ続け、**入れ直しの要らない仕組みへ移れない**。
+      // 順序を入れ替えるだけで、どちらも残す——App を入れられない組織は実在する。
+      appFirst: {
+        text: "まず、読み取りたいリポジトリのある組織に Cortex の GitHub App を入れてください。トークンの発行も、期限が来たときの入れ直しも要りません。",
+        linkText: "組織に GitHub App をインストール →",
+      },
+      how: "App を入れられない組織では、代わりにトークンを使います。GitHub → Settings → Developer settings → Personal access tokens で、対象リポジトリに Contents / Issues の Read-only を付けて発行",
     },
   };
 
@@ -4413,6 +4559,15 @@ ${capabilityState.toString()}
    * カードは #101 で能力モーダルの中へ移した（buildDataSources の pushCap 経由）。
    * まとめて並べる renderSecrets() は呼び出し元が無くなったので消してある。
    */
+  function secretPayload(intake, kind, value) {
+    var body = { projectKey: intake.projectKey, kind: kind, value: value };
+    if (kind === "backlog") {
+      var space = backlogSecretSpace();
+      if (space) body.space = space;
+    }
+    return body;
+  }
+
   function secretCard(kind, meta) {
     // **いま何で動いているか**を先に出す。入れ直したのに反映されていない状態が
     // 画面で分かるようにする（接続状況は夜間バッチのスナップショットなので、
@@ -4444,7 +4599,11 @@ ${capabilityState.toString()}
           method: "POST",
           headers: { "content-type": "application/json" },
           // **シークレット名は送らない。** どの連携かだけを送り、書き込み先はサーバが案件から決める。
-          body: JSON.stringify({ projectKey: intake.projectKey, kind: kind, value: value }),
+          // **Backlog はスペースだけ名乗る（#138）。** 名前を組み立てるのはサーバで、
+          // こちらが渡すのは「どのスペースの鍵か」という材料だけ。
+          // **押した時点で読む。** 組み立て時に固めると、接続先を登録した直後に
+          // 貼った鍵が「スペースを特定できません」で断られる
+          body: JSON.stringify(secretPayload(intake, kind, value)),
         });
         var j = await res.json().catch(function () { return {}; });
         if (!res.ok) {
@@ -4481,7 +4640,19 @@ ${capabilityState.toString()}
       // **未設定のときだけ、先に試すべき手を出す。** 既に動いているカードに
       // 「まずこれをやれ」と出すと、直す必要が無いものを触らせることになる
       !src && meta.selfServe ? el("p", { class: "sec-preferred", text: meta.selfServe.text }) : null,
+      // **本線（App）はトークンの手順より先に、いつでも出す（#138）。**
+      // トークンで動いている案件こそ App へ移してほしいので、selfServe と違って
+      // 「未設定のときだけ」にはしない
+      meta.appFirst
+        ? el("p", { class: "sec-preferred" }, [
+            document.createTextNode(meta.appFirst.text + " "),
+            el("a", { href: GITHUB_APP_INSTALL_URL, target: "_blank", rel: "noopener", text: meta.appFirst.linkText }),
+          ])
+        : null,
       el("p", { class: "sec-how", text: meta.how }),
+      // **鍵の作り方に付随する注意（招待漏れ等）。** 発行手順（how）とは別に出す——
+      // 「トークンは正しいのに読めない」は権限の問題に見えないので、切り分けに時間がかかる。
+      meta.note ? el("p", { class: "sec-how", text: meta.note }) : null,
       meta.selfServe ? el("p", { class: "sec-how", text: meta.selfServe.note }) : null,
       input,
       // **扱いの説明はカードに持たせる。** 節の見出しの下に置いていたときは、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takagaki/cortex-decisions-viewer",
-  "version": "0.4.78",
+  "version": "0.4.80",
   "description": "Cortexの意思決定記録（Decisions/*.md）を静的サイトにビルドして閲覧する。各レコードに「Edit on GitHub」リンクを付与する。",
   "license": "UNLICENSED",
   "private": false,