# ALCOMD3

Languages: English | [日本語](README.ja.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)

ALCOMD3 is an independent desktop tool for VRChat project and VPM package
management. 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.

## What is ALCOMD3?

ALCOMD3 helps manage VRChat projects, VPM repositories, packages, templates,
backups, updates, and local AI-agent visibility through MCP.

Main ALCOMD3 features:

- Material Design 3-style interface.
- Customizable application theme color.
- ALCOMD3 app name, window title, installer name, shortcuts, and icon.
- 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.
- Theme customization entry during initial setup.
- 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).

## Compatibility Notes

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.

## Downloads

Prebuilt releases are published from the ALCOMD3 repository:

<https://github.com/CQMHV/ALCOMD3>

Current ALCOMD3 releases:

- Stable: `2.0.0`
    - Release notes: [release-notes/ALCOMD3_2.0.0.md](./release-notes/ALCOMD3_2.0.0.md)
    - Windows installer: `alcomd3-2.0.0-setup.exe`
    - Windows installer zip: `alcomd3-2.0.0-setup.exe.zip`
- Beta: `2.0.1-beta.1`
    - Release notes: [release-notes/ALCOMD3_2.0.1-beta.1.md](./release-notes/ALCOMD3_2.0.1-beta.1.md)
    - Windows installer: `alcomd3-2.0.1-beta.1-setup.exe`
    - Windows installer zip: `alcomd3-2.0.1-beta.1-setup.exe.zip`

Package manager entries maintained outside this repository may not install
ALCOMD3 or use the ALCOMD3 update path. Use the release assets from this
repository when you specifically want ALCOMD3.

## Build

### Requirements

- Rust stable toolchain
- Node.js and npm
- Windows build tools when building the Windows MSVC target
- Inno Setup is downloaded/cached by the bundling task when needed

### Windows Release Installer

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

```powershell
cargo xtask release-prepare --version 2.0.1 --channel stable
cargo xtask release-build --version 2.0.1 --channel stable
cargo xtask release-publish --version 2.0.1 --channel stable
cargo xtask release-updater --version 2.0.1 --channel stable --commit --push
```

Expected release artifacts:

- `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 uses its own updater signing key. Use the ALCOMD3 updater environment
variable names for new releases.

Generate a key pair once:

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

This writes:

- `artifacts/alcomd3-updater-key/public-key-base64.txt`
- `artifacts/alcomd3-updater-key/private-key.env`
- `artifacts/alcomd3-updater-key/private-key.ps1`

Copy `public-key-base64.txt` into `vrc-get-gui/src/updater.rs` as
`static PUBLIC_KEY`. Store the two values from `private-key.env` as local
environment variables and GitHub repository secrets:

- `ALCOMD3_UPDATER_PRIVATE_KEY`
- `ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD`

Normal releases use `cargo xtask release-build`, which signs the installer,
generates updater JSON, verifies it, and copies publishable artifacts to
`artifacts/release/v{version}/`. If signing variables are not already set, it
loads `artifacts/alcomd3-updater-key/`, preferring `private-key.ps1` and
falling back to `private-key.env`. Low-level signing commands are documented in
[docs/ALCOMD3_UPDATER.md](./docs/ALCOMD3_UPDATER.md).

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

The generator expects `alcomd3-{version}-setup.exe` and its adjacent
`alcomd3-{version}-setup.exe.sig`. Verification fails if the private key used to
sign the installer does not match the public key embedded in `updater.rs`.

Known non-blocking warnings:

- `xtask/src/bundle_alcom/linux.rs` may warn about an unused `mode` variable.
- Vite may warn that `vrc-get://localhost/global-info.js` cannot be bundled
  without `type="module"`.

### Development Server

To start the Tauri development app with the Vite development server:

```powershell
cd vrc-get-gui
npm run tauri dev
```

For frontend-only development:

```powershell
cd vrc-get-gui
npm run dev
```

## Repository Layout

- `vrc-get-gui/`: ALCOMD3 desktop GUI.
- `vrc-get/`: command-line compatibility code.
- `vrc-get-vpm/`: VPM-related library code.
- `xtask/`: build, bundle, and release helper tasks.
- `docs/README.md`: documentation index and navigation entry point.
- `docs/mcp.md`: MCP bridge usage, tool, lifecycle, and troubleshooting guide.
- `docs/MAINTENANCE.md`: ALCOMD3 maintenance notes and compatibility boundaries.

## External Change Intake

ALCOMD3 uses this repository as the source of truth for branding, installer
behavior, icon assets, UI behavior, repository management features, MCP
boundaries, release flow, and GitHub configuration.

Before importing changes from another repository, read:

[docs/MAINTENANCE.md](./docs/MAINTENANCE.md)

That file records ALCOMD3 behaviors and compatibility boundaries that should be
preserved during adaptation.

## GitHub Workflows

Generic inherited GitHub workflows were removed intentionally. ALCOMD3 release
automation should be designed for this repository.

The repository currently keeps:

- `.github/ISSUE_TEMPLATE/*`

No GitHub release workflow or signing action is maintained in the repository for
now. Local release automation is provided through `cargo xtask release-*`; see
[docs/RELEASE.md](./docs/RELEASE.md).

## Licenses

The main project code is licensed under the MIT License. See
[LICENSE](./LICENSE).

The application includes an in-app Licenses page for dependency and third-party
resource notices. Important bundled third-party assets include:

- ALCOMD3 icon assets under CC BY 4.0.
- Anton font under the SIL Open Font License.
- Noto Sans font under the SIL Open Font License.

See [vrc-get-gui/THIRD-PARTY.md](./vrc-get-gui/THIRD-PARTY.md) for additional
third-party asset notes.

## Contributing

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

For contribution guidance, see:

- [CONTRIBUTING.md](./CONTRIBUTING.md)
- [vrc-get-gui/CONTRIBUTING.md](./vrc-get-gui/CONTRIBUTING.md)
