# ALCOMD3 maintenance notes

言語: [English](MAINTENANCE.md) | 日本語 | [简体中文](MAINTENANCE.zh-CN.md)

このメモは ALCOMD3 の現在の挙動、互換性境界、保守判断を記録する。ALCOMD3 の
コードを変更する場合や、外部ソースから修正を選択的に取り込む場合に使う。

### ブランディング

ALCOMD3 は独自ブランドを使いながら、既存インストールに必要な互換性ポイントを維持する。

- 製品名と表示名: `ALCOMD3`。
- Window title: `ALCOMD3`。
- Windows installer display name: `ALCOMD3`。
- Windows shortcut: `ALCOMD3`。
- Windows setup output name: `alcomd3-{version}-setup.exe`。
- インストールされる main executable は、既存 install path、protocol association、
  updater/install migration との互換性のため legacy file name を維持する。
- Windows installer は side-by-side install ではなく既存 application installation を更新する。
- `vcc://` URL shortcut association は、明示的な user choice がない場合は既定で有効。

重要ファイル:

- `vrc-get-gui/Tauri.toml`
- `vrc-get-gui/src/commands/start.rs`
- `vrc-get-gui/src/commands/util.rs`
- `vrc-get-gui/src/config.rs`
- `vrc-get-gui/bundle/windows-setup.iss`
- `xtask/src/bundle_alcom.rs`
- `xtask/src/bundle_alcom/setup_exe.rs`

### 起動とウィンドウ表示

保持する挙動:

- main window 作成時に保存済み初期サイズと maximized state を適用する。
- main window は hidden で開始し、frontend が frontend-ready command を呼んだ後に backend が表示する。
- `index.html` は first-frame background color を静的に保持し、CSS/JavaScript 読み込み前に白く点滅しないようにする。
- 通常 UI 起動前に、未対応の non-ASCII host name を拒否する。

### Material Design 3 UI

保持する挙動:

- Material Theme entry を side navigation に表示する。
- side navigation は BOOTH、VRChatAvatarLearn、version button を任意表示できる。`hide_sidebar_links` で非表示にできる。
- version button は `version: v{actual_version}` を表示し、`v{actual_version}` をコピーする。
- Toast は rounded MD3 style、MD3 semantic progress color、app base background color を使う。
- 重要な project/package action は ALCOMD3 emphasis button style を使う。
- setup と settings の文言では user-facing text に `ALCOMD3` を使う。

重要領域:

- `vrc-get-gui/app`
- `vrc-get-gui/components`
- `vrc-get-gui/app/globals.css`
- `vrc-get-gui/lib/material-theme.ts`
- `vrc-get-gui/locales/*.json5`
- `vrc-get-gui/src/config.rs`

### アイコンと第三者表示

アプリアイコンは ALCOMD3 theme color `#6cb6ff` を使い、project の third-party asset notice で扱う。

- icon を再生成するときは full logo design を保持する。
- 明示的な design decision がない限り、小さい icon size を簡略版に置き換えない。
- `vrc-get-gui/THIRD-PARTY.md` を正確に保つ。
- app 内 Licenses page は `vrc-get-gui/scripts/vite-build-license-json.ts` が生成する。

重要アセット:

- `vrc-get-gui/app-icon.png`
- `vrc-get-gui/icons/*`
- `vrc-get-gui/icon-LICENSE`
- `vrc-get-gui/third-party/Anton-Regular-OFL.txt`
- `vrc-get-gui/third-party/NotoSans-OFL.txt`

### Package operation

ALCOMD3 は package operation progress と cancellation behavior を所有する。

保持する挙動:

- install/remove/reinstall package は progress dialog を表示する。
- dialog は per-package status、overall progress、success/failure count を表示する。
- failed package は retry できる。
- long-running operation は user が terminate できる。
- operation 中に main window を閉じると即終了ではなく termination を request する。
- termination は既に成功した package を failed item に変えない。
- 可能な限り parallel package work を継続し、1 つの package failure が無関係な package を止めない。

Backend rule:

- `AbortCheck` は frontend cancellation、window-close interception、package download、package extraction、package apply step で共有する。
- Download/cache verification と zip extraction は copy chunk 間で cancellation を確認する。
- Package install/remove/reinstall progress は `TauriProjectApplyProgress` で報告する。
- Partial package failure は収集して報告し、成功済み package は完了できるようにする。

重要領域:

- `vrc-get-gui/app/_main/projects/manage`
- `vrc-get-gui/src/commands/project.rs`
- `vrc-get-gui/src/commands/start.rs`
- `vrc-get-gui/src/state/project_apply.rs`
- `vrc-get-vpm/src/traits.rs`
- `vrc-get-vpm/src/environment/package_installer.rs`
- `vrc-get-vpm/src/unity_project/pending_project_changes.rs`
- `vrc-get-vpm/src/utils/extract_zip.rs`

### Project copy、backup、restore

保持する挙動:

- Project copy は progress を表示し、cancel できる。
- Backup と restore workflow は停止して見えないよう progress を報告する。
- Main-window close handling は active long-running operation と協調し、silent interruption を避ける。

重要領域:

- `vrc-get-gui/app/_main/projects`
- `vrc-get-gui/src/commands/project.rs`
- `vrc-get-gui/src/commands/start.rs`

### Repository management

ALCOMD3 repository-management feature を保持する:

- Repository ordering / priority adjustment。
- Repository に含まれる package list の表示。

外部から package/repository management の変更を取り込む場合も、これらの機能を保持する。

重要領域:

- `vrc-get-gui/app/_main/packages/repositories`
- `vrc-get-gui/components/ReorderableList.tsx`

### MCP bridge

ALCOMD3 には optional local MCP bridge がある。将来の変更が review と UI approval flow により明示的に拡張しない限り、minimal read-only boundary を保持する。

保持する規則:

- MCP data access は既定で disabled。tool が ALCOMD3 data を返す前に GUI から有効化する必要がある。
- External MCP server は stdio 上の `alcomd3-mcp`。
- `alcomd3-mcp` の stdout は MCP JSON-RPC message のみにする。diagnostic は stderr に出す。
- GUI は起動中に private localhost TCP IPC endpoint を公開し、local data directory の `mcp/endpoint.json` に metadata を書く。
- GUI の MCP enable/disable control は tool data access のみを gate する。local endpoint を停止してはならない。disabled tool call は `mcp_disabled` を返す。
- `ALCOMD3_MCP_ENDPOINT_FILE` は development/test 用に endpoint metadata path を override できる。
- Tool は read-only: list projects、get registered project details、list repositories、search already loaded packages。
- `project_path` は details を読む前に ALCOMD3 registered project と一致する必要がある。
- MCP package search は repository refresh を強制しない。
- `initialize` と `tools/list` は GUI を起動しない。
- Actual tool call は endpoint がない場合 GUI を起動してよい。bridge は packaged/sibling ALCOMD3 GUI executable または明示的な `ALCOMD3_GUI_EXECUTABLE` override のみを起動する。
- `alcomd3-mcp` は GUI を install/update/repair してはならない。
- GUI shutdown は endpoint file を削除する。

重要領域:

- `docs/mcp.md`
- `alcomd3-mcp/`
- `alcomd3-mcp-protocol/`
- `vrc-get-gui/src/mcp.rs`
- `vrc-get-gui/src/commands/mcp.rs`
- `vrc-get-gui/app/_main/mcp/index.tsx`
- `xtask/src/build_alcom.rs`
- `xtask/src/bundle_alcom.rs`

### Updater と release

ALCOMD3 は独自の update source と signing key を使う。

保持する規則:

- Stable endpoint: `https://alcomd3.cqmhv.com/api/gui/tauri-updater.json`。
- Beta endpoint: `https://alcomd3.cqmhv.com/api/gui/tauri-updater-beta.json`。
- Update-available dialog は `https://alcomd3.cqmhv.com/` を開く official website action を含む。
- Automatic update check failure は user には silent にする。
- Manual update check は no-update と failed-update の両方で dialog を表示する。
- Version は `2.1.0-beta.1` のような SemVer string を使う。
- Updater private key は git に入れない。
- Updater installer に署名する場合は `docs/RELEASE.ja.md` と `docs/ALCOMD3_UPDATER.ja.md` に従う。
- Website updater JSON を公開する前に、serve される各 JSON file に対して `cargo xtask verify-alcom-updater-json` を実行する。

### Windows installer

保持する規則:

- Installer product name は `ALCOMD3`。
- Output setup file は `alcomd3` と version を含む。
- `VersionInfoProductVersion` は Windows-compatible numeric version を使う。
- Setup icon は `vrc-get-gui/icons/icon.ico` を使う。
- Install 時に legacy desktop/start menu shortcut を削除する。
- Installed main executable は legacy file name を維持する。

### GitHub configuration

汎用的に継承された GitHub workflow は意図的に削除されている。ALCOMD3 release automation は必要になった時点でこの repository 用に明示的に再構築する。

保持するもの:

- `.github/ISSUE_TEMPLATE/*`

現在、この repository では GitHub release workflow や signing action は保守していない。
Local release automation は `cargo xtask release-*` で保守する。詳細は `docs/RELEASE.ja.md`。

意図的に削除したもの:

- `.github/actions/sign-windows/action.yml`
- `.github/workflows/*`
- `.github/dependabot.yml`
- `.github/labeler.yml`
- `.github/scripts/*`
- `.github/copilot-instructions.md`

### Release notes と local build commands

- 現在の stable release note: `release-notes/ALCOMD3_2.0.0.md`。
- 現在の beta release note: `release-notes/ALCOMD3_2.0.1-beta.1.md`。
- 過去の release notes は `release-notes/` に保持する。
- 今後の release notes は user-visible ALCOMD3 changes を中心にする。

Windows release build:

```powershell
cargo xtask release-build --version 2.0.1 --channel stable
```

Expected outputs:

- `artifacts/release/v{version}/alcomd3-{version}-setup.exe`
- `artifacts/release/v{version}/alcomd3-{version}-setup.exe.sig`
- `artifacts/release/v{version}/alcomd3-{version}-setup.exe.zip`

Known non-blocking warnings:

- `xtask/src/bundle_alcom/linux.rs` は unused `mode` variable warning を出す場合がある。
- Vite は `vrc-get://localhost/global-info.js` が `type="module"` なしでは bundle できないと warning を出す場合がある。
