# smmodmanager

End-user mod manager for Starminer mods distributed through `smmods.com`.

This repository starts with a Rust core and CLI so the installer/update logic stays testable. The Windows executable opens the graphical manager when launched without arguments and keeps the same CLI commands available for automation.

The current Windows release ZIP includes `smmodmanager.exe` as the portable app entry point. Double-clicking it opens the manager, which auto-detects Starminer from Steam libraries when possible, still lets a player browse to a Starminer install folder, loads the SMMODS catalog, shows runtime/bridge/catalog/local/invalid mod state, installs or repairs the pinned runtime/bridge stack, installs selected catalog mods, uninstalls selected installed mods, enables or disables installed mods with valid manifests, checks for manager updates, refreshes state, and launches the game when readiness checks pass.

## Goals

- Locate or accept a Starminer install path.
- Install the pinned UE4SS runtime profile and `StarminerBridge`.
- Install mods from portal-approved packages.
- Verify package hashes and safe archive paths before extraction.
- Surface runtime, bridge, catalog, unknown local, and invalid installed mod state.
- Enable, disable, and update-check mods.
- Check the published manager release metadata for newer manager ZIPs.
- Keep base game files untouched except the manager-owned UE4SS loader and StarminerBridge install.

## Manager Model

- UE4SS is the manager-owned loader/runtime dependency. The manager installs, verifies, and repairs the pinned experimental UE4SS layout separately.
- `StarminerBridge` is a managed UE4SS mod installed under `ILLSpace\Binaries\Win64\ue4ss\Mods\StarminerBridge`.
- `StarminerBridge` packages do not include UE4SS loader files; they contain only the bridge DLL, bridge runtime, manifest, and bridge config template.
- Legacy `StarminerFramework` and `SMModding` remnants are detected and disabled during bridge enablement so they are not co-enabled with `StarminerBridge`.

## Current Commands

```powershell
cargo run -p smmodmanager -- inspect "E:\Path\To\Starminer"
cargo run -p smmodmanager -- runtime ".\starminer-ue4ss-v3.0.1-zdev.json"
cargo run -p smmodmanager -- inspect-runtime "E:\Path\To\Starminer" ".\starminer-ue4ss-v3.0.1-zdev.json"
cargo run -p smmodmanager -- manifest ".\SomeMod"
cargo run -p smmodmanager -- states "E:\Path\To\Starminer"
cargo run -p smmodmanager -- catalog-state "E:\Path\To\Starminer" ".\catalog.json"
cargo run -p smmodmanager -- catalog-state-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json"
cargo run -p smmodmanager -- launch-plan "E:\Path\To\Starminer" ".\catalog.json"
cargo run -p smmodmanager -- launch-plan-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json"
cargo run -p smmodmanager -- manager-release ".\manager-latest.json"
cargo run -p smmodmanager -- manager-release-url "https://smmods.com/api/v1/manager/latest.json"
cargo run -p smmodmanager -- publishing-contract ".\starminer-publishing-validation.v1.json"
cargo run -p smmodmanager -- publishing-contract-url "https://smmods.com/api/v1/publishing/starminer-publishing-validation.v1.json"
cargo run -p smmodmanager -- support-report "E:\Path\To\Starminer" ".\catalog.json" ".\manager-latest.json"
cargo run -p smmodmanager -- support-report-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json" "https://smmods.com/api/v1/manager/latest.json"
cargo run -p smmodmanager -- update-checks "E:\Path\To\Starminer" ".\catalog.json" ".\manager-latest.json"
cargo run -p smmodmanager -- update-checks-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json" "https://smmods.com/api/v1/manager/latest.json"
cargo run -p smmodmanager -- install-runtime "E:\Path\To\Starminer" ".\starminer-ue4ss-v3.0.1-zdev.json" ".\UE4SS-v3.0.1-zDEV" --sha256 "<hex>"
cargo run -p smmodmanager -- install-catalog "E:\Path\To\Starminer" ".\catalog.json" ".\artifact-cache" example.some-mod
cargo run -p smmodmanager -- install-catalog-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json" ".\downloads" example.some-mod
cargo run -p smmodmanager -- download-catalog-url "https://smmods.com/api/v1/catalog.json" ".\downloads" example.some-mod
cargo run -p smmodmanager -- repair-catalog "E:\Path\To\Starminer" ".\catalog.json" ".\artifact-cache" example.some-mod
cargo run -p smmodmanager -- repair-catalog-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json" ".\downloads" example.some-mod
cargo run -p smmodmanager -- install-bridge "E:\Path\To\Starminer" ".\StarminerBridge-0.1.0-dev-preview.zip" --sha256 "<hex>"
cargo run -p smmodmanager -- install-local "E:\Path\To\Starminer" ".\SomeMod.zip" --sha256 "<hex>"
cargo run -p smmodmanager -- enable "E:\Path\To\Starminer" SomeMod
cargo run -p smmodmanager -- disable "E:\Path\To\Starminer" SomeMod
```

`install-bridge` and `install-local` also accept unpacked local directories. The `--sha256` argument is optional for local smoke testing, but should be supplied for catalog-approved zip packages. `install-framework` remains available only as a legacy alias.

`runtime` validates the pinned UE4SS runtime profile published by `starminer-modding` and mirrored by `smmods.com`. `inspect-runtime` uses that profile's install layout and required loader files instead of assuming a hardcoded UE4SS layout. `install-runtime` stages and installs only the profiled UE4SS payload files into `Win64/`, preserving existing `ue4ss/Mods/` content and `mods.txt`. UE4SS repair stays separate from `StarminerBridge` package install.

`inspect` only reports the default Starminer directory shape for local package smoke testing. Runtime presence is profile-driven; use `inspect-runtime` or `catalog-state` when checking whether UE4SS is installed.

`install-catalog` is the first catalog-driven orchestration command. It reads the catalog's pinned runtime profile, bridge metadata, selected mod metadata, and dependency metadata, resolves package URLs to files in a local artifact cache, verifies SHA256 for every artifact, then installs runtime, bridge, dependency mods, and selected mods in order.

`install-catalog-url` reads the catalog from `https://`, loopback `http://` for local smoke tests, or `file://`, downloads referenced portal artifacts into a versioned local cache, verifies every SHA256, then runs the same staged installer path as cache-backed installs.

`download-catalog-url` downloads and verifies the runtime, bridge, dependency, and selected mod artifacts without changing the game install. It emits newline-delimited JSON progress events for the graphical download dialog and automation.

`catalog-state` reports machine-readable runtime, bridge, installed mod, unknown mod, invalid manifest, dependency, compatibility, and update status from the selected game install and catalog.

`launch-plan` and `launch-plan-url` are read-only launch readiness checks. They report the profiled game executable path, blocking issues such as missing runtime files or a disabled bridge, and warnings such as update-available or unknown enabled mods.

`repair-catalog` and `repair-catalog-url` reinstall the pinned runtime and `StarminerBridge` through the same staged, hash-verified catalog installer. Passing mod ids also repairs those catalog mods and their dependencies. With no mod ids, repair is limited to runtime and bridge.

`uninstall-runtime-bridge-url` removes the profiled runtime loader files and `StarminerBridge` from a selected install while preserving user mods and unrelated `mods.txt` entries. `uninstall-runtime-framework-url` remains available only as a legacy alias.

`manager-release` and `manager-release-url` validate the standalone manager release metadata published by `smmods.com`, select the requested platform (`windows-x64` by default), and report whether the running CLI version has an update available plus the release URL, SHA256, and release notes the future app UI should show.

`publishing-contract` and `publishing-contract-url` validate the bridge-owned Starminer publishing validation contract and report the manager-owned checks this build supports, including `manager_catalog_parse`.

`support-report` and `support-report-url` collect catalog metadata, manager update state, catalog install state, and launch readiness into one JSON report. They preserve per-check errors and skipped checks so support staff can diagnose bad paths, broken metadata, network failures, missing runtime files, disabled bridge state, invalid local mods, or incompatible game builds from one attachment.

`update-checks` and `update-checks-url` produce a focused manager/bridge/installed-mod update report from the same catalog state and manager release metadata used by the launcher. The report includes update candidates, SHA256/download URLs, unknown local mod counts, invalid manifest counts, incompatible installed mods, and missing dependency counts without mutating the game install.

## Project Shape

```text
crates/smmodmanager-core/  reusable install/catalog/state logic
crates/smmodmanager-cli/   command-line harness for testing core workflows
docs/                      architecture and portal contract notes
```

## Workflow Docs

- [Manager local package workflow](docs/manager-local-package-workflow.md)
- [Player guide](docs/player-guide.md)
- [Support guide](docs/support-guide.md)
- [Architecture](docs/architecture.md)
- [Portal contract](docs/portal-contract.md)
- [Manager release workflow](docs/manager-release.md)
- [GitLab CI/CD](docs/ci-cd.md)

## Copied-Game Smoke

The repeatable vertical-slice smoke runner builds the CLI, prepares a local artifact cache from the pinned UE4SS ZIP plus static site bridge/mod packages, installs from the static catalog into the copied Starminer install, verifies disable/enable toggles and launch readiness, and writes a JSON report under `reports/`:

```powershell
.\tools\Invoke-CatalogSmoke.ps1
```

The URL-backed smoke runner mirrors the static portal into a temporary local HTTP server, rewrites catalog URLs to that server, then runs `manager-release-url`, `publishing-contract-url`, `catalog-url`, `catalog-state-url`, `install-catalog-url`, disable/enable toggles, and `launch-plan-url` against the copied game:

```powershell
.\tools\Invoke-CatalogUrlSmoke.ps1
```

## Windows Release Artifact

Build the standalone Windows app plus CLI ZIP, SHA256 sidecar, release manifest, release notes, and `smmods.manager-release.v1` metadata under `dist\manager\`:

```powershell
.\tools\Build-ManagerRelease.ps1
```

## Related Repositories

- `starminer-modding`: StarminerBridge API layer, templates, schemas, examples, and release packages.
- `smmods.com`: portal, catalog, upload workflows, wiki, and app downloads.
