@takagaki/cortex-decisions-viewer 0.12.20 → 0.12.21

package/README.md

@@ -3,7 +3,7 @@
 Cortexの意思決定記録（`Decisions/*.md`）を**静的サイトにビルドして閲覧する**CLIツール。
 各レコードに「**Edit on GitHub**」リンクを付与し、閲覧画面から直接GitHubのエディタで編集できる。
 
-`md-meta-view` の代替として、Cortex専用に自前実装したもの。出力は単一の自己完結HTML（外部依存・サーバー不要）で、AWS Amplify Hosting 等の静的ホスティングにそのまま載る。
+`md-meta-view` の代替として、Cortex専用に自前実装したもの。出力は外部依存もサーバーも要らない静的ファイル一式で、AWS Amplify Hosting や S3 + CloudFront にそのまま載る。**JS と CSS は HTML に埋め込まず、`assets/` の外部ファイルに出す**——配信側（AIS ポータル）の Content-Security-Policy がインラインの `<script>` / `<style>` を実行しないため（[#301](https://github.com/classmethod-internal/cortex-tools/issues/301)）。
 
 ## 使い方
 
@@ -13,7 +13,22 @@ Cortexの意思決定記録（`Decisions/*.md`）を**静的サイトにビル
 npx -y @takagaki/cortex-decisions-viewer build --out site --title "Decisions"
 ```
 
-ビルド結果は `site/index.html`（と `404.html`）。`?id=<id>` で個別レコードに直リンクできる。
+ビルド結果は `site/` ディレクトリ一式。`?id=<id>` で個別レコードに直リンクできる。
+
+| 出力 | 中身 |
+| --- | --- |
+| `index.html` | 画面の骨組みと、埋め込みデータ（`<script type="application/json">`） |
+| `404.html` | `index.html` と同じもの（サブパス直叩きのフォールバック） |
+| `assets/viewer.<内容ハッシュ>.js` / `.css` | 画面のJSとCSS。内容が同じなら名前も同じ（版が同じなら全案件で同じ名前） |
+| `bodies/*.html` | レコードの本文（詳細を開いたときに取りに行く） |
+| `thumbs/*` | グラフのサムネイル画像 |
+
+**配置は `site/` を丸ごと置く**（`index.html` だけを置いても画面は出ない）。
+ファイル名を内容ハッシュにしているのは、`Cache-Control` を付けずに置かれた
+`index.html` をブラウザが発見的にキャッシュするため——固定名だと
+「利用者の手元に残った古い `index.html` が、消えた JS を指す」形になり、
+強制再読み込みまで画面が真っ白になる。中身が変われば URL も変わるなら起きない。
+配置側では `index.html` / `404.html` を `no-cache`、`assets/` を長期キャッシュにするとよい。
 
 ## CLI
 

package/dist/build.js

@@ -1888,7 +1888,26 @@ async function build(opts) {
     // 本文HTML（リッチ・かさばる）を bodies/ へ外出しし、inlineデータからは除外する。
     // 一覧・グラフ・検索は inline の searchText（軽量plaintext）で動き、詳細表示時にbodyRefをfetchする。
     await externalizeBodies(site, outAbs);
-    const html = (0, render_1.renderSite)(site);
+    // CSSとJSは外部ファイルへ出す。**インラインのままだと配信先で画面が出ない**——
+    // AISポータルは /p/<案件>/cm/ に厳格な Content-Security-Policy を返しており、
+    // インラインの style / script を実行しない（cortex-tools #301）。
+    //
+    // ファイル名を内容ハッシュにする理由: 配置先の S3 は Cache-Control を付けずに
+    // 置かれ、ブラウザは Last-Modified からの発見的キャッシュをする。固定名だと
+    // 「利用者の手元に残った古い index.html が、消えた JS を指す」形になり、
+    // 強制再読み込みまで真っ白になる。中身が違えば URL も違うなら、それが起きない。
+    //
+    // 配置側（cortex-engine の build-viewer.yml）の責務: aws s3 sync --delete が
+    // 古いハッシュのファイルを消すこと、index.html に Cache-Control: no-cache を
+    // 付けること（assets/ は内容ハッシュ名なので長期キャッシュでよい）。
+    const assetSources = (0, render_1.viewerAssetSources)();
+    const assets = (0, render_1.viewerAssetNames)(assetSources);
+    await node_fs_1.promises.mkdir(path.join(outAbs, "assets"), { recursive: true });
+    await node_fs_1.promises.writeFile(path.join(outAbs, assets.css), assetSources.css, "utf8");
+    await node_fs_1.promises.writeFile(path.join(outAbs, assets.js), assetSources.js, "utf8");
+    // **renderSite ではなく renderSiteWithAssets を呼ぶ。** 引数を1つ落としても
+    // 型が通ってしまう形にすると、本番の出力が黙ってインラインに戻る
+    const html = (0, render_1.renderSiteWithAssets)(site, assets);
     await node_fs_1.promises.writeFile(path.join(outAbs, "index.html"), html, "utf8");
     // SPA的フォールバック（?id= はクエリなので不要だが、サブパス直叩き対策として404も用意）
     await node_fs_1.promises.writeFile(path.join(outAbs, "404.html"), html, "utf8");

package/dist/render.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UNSETTLED_LIMITS = exports.LIVE_CONFIRM_LIMITS = void 0;
 exports.renderSite = renderSite;
+exports.renderSiteWithAssets = renderSiteWithAssets;
+exports.viewerAssetSources = viewerAssetSources;
+exports.viewerAssetNames = viewerAssetNames;
 exports.sanitizeRegisteredNow = sanitizeRegisteredNow;
 exports.sanitizeHarnessSchedules = sanitizeHarnessSchedules;
 exports.sanitizeHarnessShelf = sanitizeHarnessShelf;
@@ -29,9 +32,19 @@ exports.ingestedAtOf = ingestedAtOf;
 exports.keyMissingText = keyMissingText;
 exports.deriveCapTile = deriveCapTile;
 exports.renderConnectionMap = renderConnectionMap;
+const node_crypto_1 = require("node:crypto");
 const meet_guide_images_1 = require("./meet-guide-images");
-/** SiteDataを単一の自己完結HTML（埋め込みデータ+CSS+JS）にレンダリングする */
-function renderSite(site) {
+/**
+ * SiteDataをHTMLにレンダリングする。
+ *
+ * `assets` を渡すと、CSSとJSを**外部ファイルへの参照**（link/script src）で出す。
+ * 配信側（AISポータル）の Content-Security-Policy がインラインの style / script を
+ * 実行しないため（cortex-tools #301）。本番の出力（build()）は必ずこちら。
+ *
+ * `assets` 省略時は従来どおり単一の自己完結HTML（埋め込みデータ+CSS+JS）を返す。
+ * JSDOM で画面を動かす既存テストがこの形に依存している（外部ファイルは読まれない）。
+ */
+function renderSite(site, assets) {
     // </script> によるブレイクアウトを防ぐため < をエスケープして埋め込む
     // Claude Code Web ディープリンク（この案件リポ＋狙ったプロンプトで開く）。repoBaseUrl から slug を導出（追加入力なし）。
     const repoSlug = site.repoBaseUrl
@@ -54,6 +67,13 @@ function renderSite(site) {
         ? `<a class="gh-btn" href="${escapeHtml(site.repoBaseUrl)}" target="_blank" rel="noopener" title="コンテキストリポジトリをGitHubで開く">${GITHUB_ICON}</a>`
         : "";
     const askBtn = `<a class="ask-ai-btn" href="${escapeHtml(askUrl)}" target="_blank" rel="noopener" title="Claude Code Web でこの案件のリポジトリを開き、プロジェクトについて質問・調査できます">💬 プロジェクトについてAIに聞く</a>`;
+    // CSPでインラインが拒否される環境向けの外部参照形。省略時は従来どおり埋め込む
+    const styleTag = assets
+        ? `<link rel="stylesheet" href="${escapeHtml(assets.css)}" />`
+        : `<style>${CSS}</style>`;
+    const scriptTag = assets
+        ? `<script src="${escapeHtml(assets.js)}"></script>`
+        : `<script>${CLIENT_JS}</script>`;
     return `<!DOCTYPE html>
 <html lang="ja">
 <head>
@@ -61,7 +81,7 @@ function renderSite(site) {
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <meta name="robots" content="noindex, nofollow" />
 <title>${safeTitle}</title>
-<style>${CSS}</style>
+${styleTag}
 </head>
 <body>
 <header class="site-header">
@@ -77,7 +97,7 @@ function renderSite(site) {
 </footer>
 ${connMap ? `<template id="conn-map">${connMap}</template>\n` : ""}<script type="application/json" id="tutorial-data">${tutorialJson}</script>
 <script type="application/json" id="site-data">${dataJson}</script>
-<script>${CLIENT_JS}</script>
+${scriptTag}
 </body>
 </html>`;
 }
@@ -89,6 +109,31 @@ function escapeHtml(s) {
         .replace(/>/g, "&gt;")
         .replace(/"/g, "&quot;");
 }
+/**
+ * 外部ファイル参照の形でレンダリングする（assets必須）。
+ *
+ * build() はこちらだけを呼ぶ。renderSite は assets を省略できるので、
+ * 本番の出力にインラインが戻る退行を型で止められない。その1点のための薄い関数。
+ */
+function renderSiteWithAssets(site, assets) {
+    return renderSite(site, assets);
+}
+/** 外部ファイルへ書き出す中身。埋め込み形（renderSite の assets 省略時）と同一の文字列 */
+function viewerAssetSources() {
+    return { css: CSS, js: CLIENT_JS };
+}
+/**
+ * 中身から外部ファイル名を決める。
+ *
+ * 内容ハッシュ（sha256の先頭8桁）にするのは、配信先がブラウザのキャッシュを
+ * 持つため。固定名だと「古いHTMLと新しいJS」の組み合わせが起こりうるが、
+ * 中身が変われば名前も変わるなら起こらない。**同じ中身なら同じ名前**なので、
+ * 版が同じかぎり全案件で同じファイル名になる。
+ */
+function viewerAssetNames(sources) {
+    const h = (text) => (0, node_crypto_1.createHash)("sha256").update(text, "utf8").digest("hex").slice(0, 8);
+    return { css: `assets/viewer.${h(sources.css)}.css`, js: `assets/viewer.${h(sources.js)}.js` };
+}
 /** 接続マップの能力定義（表示順・絵文字は詳細カードの流儀を踏襲） */
 /**
  * アダプタのロゴ。**公式配布のSVGをそのまま埋め込む。**

package/package.json

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