Imported from 1llum1n4t1s/EXLSXS (AGENTS.md). Install upstream with npx skills add 1llum1n4t1s/EXLSXS. Copyright stays with the author.

AGENTS.md — EXLSXS

This file provides guidance to Codex and other coding agents working in this repository.

Excel 用 VSTO アドイン（リボンから全シートの表示倍率・表示モード・フォント・選択位置を一括整形）を Velopack で配布するプロジェクト。

構成

• EXLSXS/ — VSTO アドイン本体 (.NET Framework 4.8.1・legacy csproj)
• EXLSXS.Host/ — Velopack ホスト (.NET 10)。インストール/更新時の VSTO 登録・起動時サイレント更新
• build/pack-velopack.ps1 — VSTO publish → host publish → Velopack pack（staging はフラット構成必須、下記参照）
• scripts/release-local.ps1 — 署名付きローカルリリース（ビルド → 署名 → 検証 → R2 アップロード）
• ../vps-web/lp/exlsxs/ — VPS配信のランディングページ（exlsxs.kagayoi.com）
• Directory.Build.props — バージョンの唯一の定義場所（<Version>、他は全部ここから導出）
• DESIGN.md — 現行システムの構造、責務、データフロー、設計判断の正本

主要コマンド

# ビルド
MSBuild EXLSXS.slnx /t:Restore,Rebuild /p:Configuration=Release /p:Platform="Any CPU"
dotnet build EXLSXS.Host/EXLSXS.Host.csproj -c Release

# ホストのテスト
dotnet test EXLSXS.Host.Tests/EXLSXS.Host.Tests.csproj -c Release

# 署名付きパック（R2 アップロード無し）
pwsh -NoProfile -File scripts/release-local.ps1 -SkipUpload

# リリース（署名 + R2 アップロード。SimplySign ログイン必須）
pwsh -NoProfile -File scripts/release-local.ps1

# ランディングページのデプロイ（リポジトリルートから実行・--config でファイル明示が必須）
pwsh ../vps-web/deploy/deploy-lp.ps1

守ること（実機で踏んだ罠）

• vsto staging はフラット構成を維持する: .vsto / .dll.manifest / EXLSXS.dll / 依存 DLL を同一フォルダに並べる。vstolocal 登録は .vsto と同じフォルダを AppBase にするため、ClickOnce のネスト構成 (Application Files\<name>_<ver>\) のまま登録すると Assembly.Load("EXLSXS") が FileNotFoundException でアドインが読み込めない
• publish は MapFileExtensions=false をコマンドライン /p: で渡す: csproj の PropertyGroup 値は VSTO publish ターゲットに上書きされる。.deploy 拡張子が付くと vstolocal がファイルを見つけられない
• VSTO ランタイム検出は v4 と v4R の両キーを見る: Office/VS 同梱導入は v4、再頒布パッケージは v4R に登録される
• EmbedInteropTypes=True のため COM イベントは += で購読する: 文字列ベースの ComAwareEventInfo はイベントメタデータが埋め込まれず NullReferenceException になる
• バージョンは Directory.Build.props の <Version> だけを更新する: csproj の ApplicationVersion / AssemblyVersion / host の版数はすべて導出
• Velopack ライブラリと vpk CLI は同じ安定版に揃える: ライブラリ版は EXLSXS.Host/EXLSXS.Host.csproj、CLI 版は build/pack-velopack.ps1 の $vpkVersion が正本。片方だけ更新せず、同じ batch で更新して pack 動作を確認する
• VS2026 で開くには (1) csproj に標準 VSTO デザイナー構成を持たせ、(2) .slnx の VSTO プロジェクト行に Type 属性を付けない: VS2026 でも VSTO は正式サポート（公式テンプレートが同梱され、新規テンプレートは正常にロードする）。EXLSXS が読み込めなかった原因は 2 つあり両方を満たす必要がある。
  • (1) csproj 側: <ProjectExtensions> の <FlavorProperties GUID="{BAA0C2D2-18E2-41B9-852F-F413020CAA33}"> に ProjectCreationSetting="1" 付き <ProjectProperties> と <Host Name="Excel" GeneratedCodeNamespace="EXLSXS"><HostItem ... Blueprint="ThisAddIn.Designer.xml" GeneratedCode="ThisAddIn.Designer.cs" /></Host> を持たせ、ThisAddIn.Designer.xml（Blueprint）と ThisAddIn.Designer.cs（生成コード相当: partial class ThisAddIn の生成メンバ + Globals + ThisRibbonCollection）を実体として置く。ThisAddIn.cs はユーザーコードのみにする。この <Host>/<HostItem> 宣言が無いとフレーバー初期化がアサート (GUID が空です。 パラメーター名:serviceGuid) で失敗する（MSBuild ビルドは Host 宣言が無くても通るため気付きにくい）。
  • (2) .slnx 側: VSTO プロジェクト行は <Project Path="EXLSXS/EXLSXS.csproj" /> と Type 属性なし で書く。Type 属性なしだと VS は拡張子で C# 基底型を判定し csproj の <ProjectTypeGuids>（{BAA0C2D2};{FAE04EC0} の 2 段チェーン）を読んでフレーバーをアグリゲートする。Type="{BAA0C2D2-...}" を付けると外側フレーバー GUID だけが指定され基底型が欠けてアグリゲーションが壊れ「読み込みに失敗しました」になる（過去にこの Type 属性を回避策として入れていたが逆効果だった）。
  • 検証: EXLSXS.csproj を直接開く / .slnx（Type 無し）を開く のどちらでも ソリューション 'EXLSXS' (3/3 のプロジェクト) で EXLSXS が Excel ホストノード付きでロードされること。SDK のホスト/テストは Type 属性不要。
• リボン/コードを変えたら %LOCALAPPDATA%\assembly\dl3 を消してから Excel を起動して動作確認する: EXLSXS は strong-name 付きで、同じ <Version> から生成した $(Version).0 のビルドは同じアセンブリ identity を持つ。VSTO/Fusion は同一バージョンの新ビルドを「同じ物」とみなして dl3 の旧コピーを読み続けるため、bin\Debug/Release を再ビルドしても Excel に反映されない。dev 反復での確認手順は「Excel 終了 → rm -rf %LOCALAPPDATA%/assembly/dl3 → Excel 起動」。Debug と Release は identity が同一なので Fusion がどちらのコピーを使うか不定 → 確実を期すなら両構成を再ビルドしてからキャッシュを消す。リリース時は /vava でバージョンが上がり identity が変わるため、この罠はエンドユーザーには出ない（dev 専用）
• 製品ページの配信は vps-web/deploy/deploy-lp.ps1 を使う。公開ホスト・更新ファイルの既存経路を維持する。
• Velopack 配信の固定名ファイルはアップロード後に Cloudflare キャッシュをパージする: EXLSXS-win-Setup.exe / releases.win.json / RELEASES / EXLSXS-win-Portable.zip / assets.win.json は URL 不変で毎リリース中身が変わるため、R2 へ上げても Cloudflare エッジが旧版を Cache-Control: max-age=14400（4 時間）保持し、新規ダウンロード・自動更新が旧バージョンを掴む（症状: 配信 manifest は新版なのにページから DL した Setup.exe が旧版。CF-Cache-Status: HIT + 古い Last-Modified で判別できる）。scripts/release-local.ps1 は新旧両ホストの固定名 URL を purge_cache API でパージし、releases.win.json を cache-busting / no-cache なしで取得してローカル manifest との一致を確認する（バージョン付き nupkg は URL が一意なのでパージ不要）。ただし公開 Setup.exe の実体一致までは自動確認しないため、フルリリース後は両ホストの固定 URL から Setup.exe を取得し、ローカル成果物とのサイズ・SHA-256 一致と Authenticode Valid を確認する。不一致なら対象 URL を再パージして再確認する。手動アップロード時も同じ検証を行う

ドメイン移行（2026-07 開始・期限 2027/05/31）

屋号を Kagayoi に統一したため、配信ドメインを nephilim.jp から kagayoi.com へ移行中。方針の全体像はユーザーグローバルの CLAUDE.md §屋号とドメイン を参照する。

• 旧ドメイン nephilim.jp はレジストラで廃止申請済みで 2027/05/31 に失効する（延長しない）。それまでに出荷済みバイナリを新ドメインへ移行しきる。
• 旧ホストの Worker route / custom domain は期限まで消さない。消すと出荷済みアプリの自動更新が止まる。
• nephilim.jp の Redirect Rules は / だけを 301 する。releases.*.json / *.nupkg / *-Setup.exe は転送せず R2 が配信を続ける。
• 配信は exlsxs.kagayoi.com（R2 exlsxs-updates）。旧 exlsxs.nephilim.jp は route に併記して残してある。

製品ページの配信先

製品ページの配信HTMLは ../vps-web/lp/exlsxs/（編集元は ../vps-web/tools/lp/templates/）、公開実体はVPSの /srv/www/lp/exlsxs/。 Cloudflare側の中継設定は ../vps-web/deploy/lp-gateways/exlsxs/ に置く。 公開URLと既存のR2・ライセンス通信を維持し、配信は vps-web/deploy/deploy-lp.ps1 へ統一する。