plugin-helper/docs/notes/naluluna-mod-assistant.md

# NalulunaModAssistant Source and Install Notes

This note records how NalulunaModAssistant behaves when used to install
Patreon-only Naluluna mods. It is intended to guide future `plugin-helper`
support for private/local payloads without checking private artifacts,
session-specific URLs, or account data into the repo.

Observed run:

- Date: 2026-06-29
- Assistant path: `C:\Users\pleb\Apps\Naluluna\NalulunaModAssistant.exe`
- Assistant version: `1.5.1`
- Runtime UI: WebView2 `149.0.4022.80`
- Log path: `C:\Users\pleb\Apps\Naluluna\Logs\NalulunaModAssistant\_latest.log`

## High-Level Flow

NalulunaModAssistant is a WebView2 desktop app. It authenticates the user through
an embedded browser, fetches a versioned mod catalog, then downloads selected
plugin archives into a temporary working directory before extracting them into
the configured Beat Saber directory.

The observed Patreon flow was:

1. Initialize WebView2 and a temporary working directory.
2. Load the initial catalog JSON named `start`.
3. Navigate to Patreon at `https://www.patreon.com/c/naluluna/posts`.
4. Resolve the NalulunaModAssistant files post:
   `https://www.patreon.com/naluluna/posts/nalulunamodassis-74489236`.
5. Confirm the logged-in Patreon account has access.
6. Detect Beat Saber version `1.44.1`.
7. Select mod list version `1.42.0`.
8. Fetch the catalog JSON named `1-42-0`.
9. Download selected archives and extract their payloads into the configured
   Beat Saber tree.

The assistant binary also contains a `GetJsonFromGoogleSiteAsync` code path and
Fanbox login/status paths. Those appear to be alternate or older source flows.
The 2026-06-29 run used Patreon, not Google Sites, GitHub, BeatMods, or Fanbox.

## Source Model

Naluluna plugin artifacts are not normal public GitHub or BeatMods releases.
For Patreon installs, the authoritative source is the private
NalulunaModAssistant Patreon post and its attachment metadata.

The assistant downloads files through two forms:

- Relative catalog paths such as `nma/files/NalulunaUtils-5.7.0-bs1.44.0.zip`
  and `nma/imgs/NalulunaCounters.jpg`.
- Patreon file endpoints such as `https://www.patreon.com/file?...`, which
  resolve to tokenized `patreonusercontent.com` CDN URLs after authentication.

Do not record tokenized CDN URLs, cookies, WebView profile data, or private
account identifiers in repo files. They are session-specific and may grant access
to paid artifacts. For lockfile-style notes, record the Patreon post, the
assistant-visible archive name, the mod version, the Beat Saber target string,
the installed paths, and local file hashes when available.

## Catalog Versioning

In the observed run, the game was `1.44.1` but the assistant selected
`modListVersion: 1.42.0` and fetched catalog node `1-42-0`.

That means the assistant's catalog version should not be assumed to exactly
match the game version. Treat it as an upstream compatibility bucket. For
documentation and locks, record both values:

- actual game version reported by the assistant
- mod list version selected by the assistant

## Install Target

The assistant reads and writes a configured Beat Saber directory, not a
BSManager instance root chosen by `plugin-helper`.

Observed config:

- Beat Saber directory:
  `C:\Program Files (x86)\Steam\steamapps\common\Beat Saber`
- Working directory:
  `C:\Users\pleb\AppData\Local\Temp\tmp97E.tmp`

This matters because the observed run installed into the Steam Beat Saber tree,
not the BSManager `1.44.1` instance at
`C:\Users\pleb\BSManager\BSInstances\1.44.1`.

Before using NalulunaModAssistant as a source for a BSManager instance, either:

- point the assistant at the intended BSManager instance root, if the UI allows
  it, or
- treat the Steam install as a staging source and copy exact installed files into
  the target instance through a `plugin-helper` local/private payload workflow.

Do not manually copy files into the live instance as a substitute for
`plugin-helper` state tracking unless this is an explicit one-off recovery step.

## Extraction Behavior

Archives are extracted relative to the Beat Saber directory. The observed
payloads wrote to these top-level areas:

- `Plugins/`
- `Libs/Native/`
- `UserData/NalulunaUtils/`
- `UserData/NalulunaSkybox/`
- `NalulunaAvatars/`

Examples from the observed run:

- `Plugins/NalulunaUtils.dll`
- `Plugins/NalulunaAvatars.dll`
- `Plugins/NalulunaSkybox.dll`
- `Plugins/NalulunaSkyboxSamples.manifest`
- `Libs/Native/OVRLipSync.dll`
- `UserData/NalulunaUtils/OpenVRHelper/OpenVRHelper.exe`
- `UserData/NalulunaSkybox/*.jpgx`
- `NalulunaAvatars/AliciaSolid.vrm`

Some packages install manifests or data assets instead of a plugin DLL. A
`plugin-helper` implementation should record every extracted file, not just the
primary DLL.

## Observed Install Batch

The 2026-06-29 run installed the following selected packages:

- `NalulunaShaders` `2.1.3`, archive
  `NalulunaShaders-2.1.3-bs1.39.1.zip`
- `NalulunaUtils` `5.7.0`, archive
  `NalulunaUtils-5.7.0-bs1.44.0.zip`
- `AliciaSolid` `1.10.0`, archive
  `AliciaSolid-1.10.0-bs1.26.0.zip`
- `NalulunaAvatars` `1.10.0`
- `NalulunaSkybox` `2.0.0`
- `OpenVRHelper` `0.2.3`
- `NalulunaRewinder` `1.2.0`
- `NalulunaCounters` `1.3.2`
- `NalulunaEnergy` `1.1.0`
- `NalulunaLevelDetail` `2.0.0`
- `NalulunaSongPreview` `1.0.1`
- `NalulunaSkyboxSamples` `1.1.0`

The first `NalulunaUtils` attempt downloaded successfully but failed extraction
with a Windows file-lock error:

```text
The process cannot access the file
'C:\Users\pleb\AppData\Local\Temp\tmp97E.tmp\NalulunaUtils-5.7.0-bs1.44.0.zip'
because it is being used by another process.
```

A later retry succeeded and extracted `Plugins/NalulunaUtils.dll`.

Several downloads log `download interrupted: FileSecurityCheckFailed` after a
successful install. In the observed run, those messages did not necessarily mean
the mod failed; the assistant logged `Installed: ...` first. Treat this message
as a warning to cross-check against extracted files and the assistant's final
success/failure count.

## Implications for plugin-helper

Private Naluluna payloads should be modeled as local/private artifacts rather
than first-class remote fetches until there is an explicit supported way to
authenticate and download them safely.

Recommended near-term workflow:

1. Use NalulunaModAssistant to download/install into a staging Beat Saber tree.
2. Inspect the assistant log for selected package names, versions, archive names,
   and extracted paths.
3. Hash the installed files or preserved archives.
4. Add a `plugin-helper` local/private payload entry for each package.
5. Apply that payload to the intended BSManager instance with normal install
   state recording.
6. Smoketest the BSManager instance and record results in
   `docs/notes/install-and-verify-plugins-1.44.1.md`.

Longer term, `plugin-helper` could add a "local archive import" command that
accepts a zip from the assistant's working directory or a saved local cache,
normalizes the extracted paths, computes hashes, and creates an auditable
install plan without needing to understand Patreon authentication.

## What Not To Commit

Do not commit:

- downloaded private plugin archives
- tokenized `patreonusercontent.com` URLs
- WebView2 profile data
- Patreon or Fanbox cookies
- full `_patreon.log` / `_fanbox.log` captures
- account identifiers from logs

Safe to commit:

- assistant version
- Patreon post URL
- package names and versions
- non-tokenized archive names shown by the assistant
- extracted relative paths
- hashes of local artifacts or installed files
- compatibility and smoketest notes