@takagaki/cortex-decisions-viewer

Cortexの意思決定記録（Decisions/*.md）を静的サイトにビルドして閲覧するCLIツール。 各レコードに「Edit on GitHub」リンクを付与し、閲覧画面から直接GitHubのエディタで編集できる。

md-meta-view の代替として、Cortex専用に自前実装したもの。出力は単一の自己完結HTML（外部依存・サーバー不要）で、AWS Amplify Hosting 等の静的ホスティングにそのまま載る。

使い方

# リポジトリのルートで実行する（git remote から GitHub URL を解決し、編集リンクを生成するため）
# dir未指定なら Cortex/Decisions/records → Cortex/Decisions → Decisions の順で自動検出
npx -y @takagaki/cortex-decisions-viewer build --out site --title "Decisions"

ビルド結果は site/index.html（と 404.html）。?id=<id> で個別レコードに直リンクできる。

CLI

cortex-decisions-viewer build [dir] [options]

| 引数 / オプション | 既定値 | 説明 | | --- | --- | --- | | [dir] | Decisions | Decisionsディレクトリ（リポジトリルートからの相対 or 絶対） | | -o, --out <dir> | site | 出力ディレクトリ | | -t, --title <title> | Decisions | サイトタイトル | | --repo-url <url> | （git remoteから解決） | GitHubリポジトリURL。CIで git remote が引けない場合に明示指定 | | --branch <branch> | main（環境変数 AWS_BRANCH があればそれ） | 編集リンク・参照リンクが指すブランチ | | --exclude <files...> | （なし） | 一覧から除外する追加ファイル名。既定で README.md / template.md は除外 |

入力（Decisionファイル）の仕様

Decisions/*.md の frontmatter を読む（README.md / template.md は自動除外）。

| フィールド | 用途 | | --- | --- | | id | 一意キー。?id= のディープリンクに使用（無ければファイル名から導出） | | title | タイトル | | date | 日付（YYYY-MM-DD）。一覧は日付降順。期間（月）フィルタの導出元 | | sprint | フィルタ用（sprint を使っている案件のみフィルタ表示） | | category | フィルタ用＋カテゴリーバッジ | | deciders | 決定者チップ | | summary | 一覧・詳細の要約 | | references | 参照リンク。[label](url) 形式・URL・リポジトリルート相対パスに対応（ローカルパスはGitHubのblobリンクに変換） | | 本文 | markdownをHTML化して詳細に表示（先頭のH1はタイトルと重複するため自動除去） |

機能

• 一覧（カード）＋キーワード検索＋期間（月）フィルタ＋categoryフィルタ
  • 期間フィルタは date から YYYY-MM を導出（2026年4月 のように表示）
  • sprintフィルタは sprint を使っている案件でのみ自動表示（NTV等。未使用の案件では非表示）
• 詳細表示（?id= ディープリンク、ブラウザの戻る対応）
• 各レコードに「GitHubで編集」ボタン（<repo>/edit/<branch>/<path>）
• noindex 付与（検索エンジンにインデックスさせない）

開発

npm install
npm run build          # tsc → dist/
npm run demo           # ../../aidd-project-cortex の Cortex/ をビルドして .demo-site/ に出力

位置づけ（cortex-tools モノレポ）

このパッケージは、Cortex関連の自動化・基盤を集約するモノレポ（cortex-tools 構想）の viewer/ として配置する想定。 同リポジトリには infra/（GitHub OIDC + Bedrock 用 CDK）や、再利用可能なGitHub Actions ワークフローを並置していく。

• 器テンプレート（aidd-project-cortex）にはビューアのソースを置かない。各案件のAmplifyビルドが npx @takagaki/cortex-decisions-viewer で参照するだけにし、テンプレートをクリーンに保つ。