# ALCOMD3 GUI

[![Github Release][shields-github-version]][release-alcomd3]

[shields-github-version]: https://img.shields.io/github/v/release/CQMHV/ALCOMD3
[release-alcomd3]: https://github.com/CQMHV/ALCOMD3/releases

ALCOMD3 is the desktop GUI for ALCOMD3's VRChat project and VPM package
management workflow. It provides project workflows, VPM repository and package
management, Windows releases and updates, and optional local MCP integration.
The project originated from vrc-get/ALCOM.

This project is not an official product of VRChat or VCC.

Current ALCOMD3 releases:

- Stable: `2.0.0`
- Beta: `2.0.1-beta.1`

## What ALCOMD3 Provides

ALCOMD3 owns the user-facing desktop experience, including the app name, window
title, installer display name, shortcuts, icon, updater endpoints, and release
artifacts.

Main ALCOMD3 features in the current release:

- Material Design 3-style interface.
- Customizable application theme color.
- Theme customization entry during the initial setup flow.
- VPM repository ordering / priority adjustment.
- Ability to view the package list contained in a repository.
- Package operation progress windows with per-package status, retry, and
  termination support.
- Project copy progress dialogs with cancellation and coordinated task handling.
- Backup progress display and restore-from-backup workflow.
- Safer project removal behavior that keeps the project entry when directory
  deletion fails.
- ALCOMD3 update source, update dialog website entry, and official website
  download fallback.
- `vcc://` URL shortcut association is enabled by default.
- Startup and Windows URL-opening stability fixes.
- Windows installer files use versioned `alcomd3` names, for example
  `alcomd3-2.0.0-setup.exe`.
- Optional local MCP bridge with read-only project, repository, and package
  tools. See [../docs/mcp.md](../docs/mcp.md).

## Installation

The recommended way to install ALCOMD3 is to download a prebuilt release from
the ALCOMD3 repository:

[https://github.com/CQMHV/ALCOMD3/releases][release-alcomd3]

For each version, the expected Windows release artifacts are:

- `alcomd3-{version}-setup.exe`
- `alcomd3-{version}-setup.exe.zip`

Package manager entries maintained outside this repository may not install
ALCOMD3 or use the ALCOMD3 update path.

## Windows Compatibility

The Windows installer keeps the existing application install path and protocol
associations compatible.

- Installing ALCOMD3 on Windows updates the existing application installation
  instead of installing side by side.
- The installed main executable keeps its legacy file name for compatibility
  with the existing install path and protocol associations.
- User-facing application branding is ALCOMD3.

## Updates

Automatic update checks use the ALCOMD3 update source.

- Stable endpoint:
  `https://alcomd3.cqmhv.com/api/gui/tauri-updater.json`
- Beta endpoint:
  `https://alcomd3.cqmhv.com/api/gui/tauri-updater-beta.json`

Automatic update check failures are intended to stay silent for users. Manual
update checks should still report no-update and failed-update results in the
app.

When an update is available, the app should provide an official website button
that opens `https://alcomd3.cqmhv.com/` in addition to any automatic update
install button that is available for that release.

## Supported Platforms

ALCOMD3 targets modern Windows, macOS, and Linux environments. Windows release
artifacts are the currently maintained release target; Linux support is treated
as best-effort community support.

Platform notes:

- macOS uses the built-in WKWebView.
- Windows uses WebView2 and expects a supported Microsoft Edge WebView2 runtime.
- Linux requires modern webkit2gtk 4.1 and is not guaranteed on every
  distribution.

## Requirements for Building

To build ALCOMD3, you need:

- [Node.js] >=20 to build the web frontend.
- [npm] v10, usually bundled with Node.js.
- [cargo] and a current Rust stable toolchain.
- Platform dependencies required by
  [Tauri v2](https://v2.tauri.app/start/prerequisites/#system-dependencies).

[Node.js]: https://nodejs.org/en
[npm]: https://www.npmjs.com
[cargo]: https://doc.rust-lang.org/cargo/

## Building

The complete ALCOMD3-owned release workflow is documented in
[../docs/RELEASE.md](../docs/RELEASE.md).

Use the repository `xtask` command from the repository root:

```bash
cargo xtask build-alcom --release
```

This command builds the web frontend, the main ALCOMD3 executable, and the
`alcomd3-mcp` bridge for the current platform. For cross-compilation, add the
`--target` command-line parameter. The executables will be created in the
`target/release` directory or the matching target-specific directory.

You can disable the self-updater with the `--no-self-updater` option. This does
not disable update checks; ALCOMD3 will show a message when a newer release is
available instead of offering a self-update.

Always build the executable with `cargo xtask build-alcom` before creating a
production bundle.

```bash
cargo xtask bundle-alcom --release --bundles <bundles>
```

Check `--help` for the list of supported bundle types.

For example, to build the Windows x64 installer:

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

The release artifacts will be copied to:

```text
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
```

## Updater Signing

ALCOMD3 updater payloads are signed with ALCOMD3-owned minisign keys.

Generate a key pair once:

```powershell
$env:ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD="your-password"
cargo xtask generate-alcom-updater-key
```

Copy `artifacts/alcomd3-updater-key/public-key-base64.txt` into
`src/updater.rs` as `static PUBLIC_KEY`. Keep the generated private key secret
and expose it to signing jobs with these names:

- `ALCOMD3_UPDATER_PRIVATE_KEY`
- `ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD`

Normal releases use `cargo xtask release-build`, which signs the setup exe,
generates updater JSON, and verifies that the JSON signature matches the
embedded public key. If signing variables are not already set, it loads
`artifacts/alcomd3-updater-key/`, preferring `private-key.ps1` and falling back
to `private-key.env`.

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

Do not use a plain `cargo build -p vrc-get-gui` binary for bundling a
production installer. It may miss the production frontend setup and required
feature flags.

## Development

ALCOMD3 is based on Tauri and React/Vite.

Run the Tauri development app from this directory:

```bash
npm run tauri dev
```

For frontend-only development:

```bash
npm run dev
```

## Contribution

This repository is maintained for ALCOMD3. Issues and pull requests should
focus on ALCOMD3 GUI behavior, documentation, releases, compatibility, and
tooling.

For general contribution guidance, see [../CONTRIBUTING.md](../CONTRIBUTING.md)
and [CONTRIBUTING.md](CONTRIBUTING.md).

## License

ALCOMD3 is licensed under the MIT License. See [../LICENSE](../LICENSE) for
more information.
