# StudioBridge — Update Procedure (runbook for AI agents)

This document is a **step-by-step todo checklist** that an AI agent (or the user)
follows to update the portable StudioBridge bundle to the latest upstream release
from [Rdiger-36/StudioBridge](https://github.com/Rdiger-36/StudioBridge).

**Goal:** check for updates on GitHub → download the new source → rebuild the
complete `StudioBridge.jar` fat bundle → deploy it to `portable-dist/` together
with the launchers.

---

## Preconditions (check before starting)

- [ ] Internet access is available (needed for GitHub API, git, Maven Central).
- [ ] Git is installed (`git --version`).
- [ ] Maven is available. The project uses a portable Maven at
      `%LOCALAPPDATA%\Programs\apache-maven-3.9.9\bin\mvn.cmd`
      (see `StudioBridge-src/rebuild-jar.bat`). If missing, install Maven 3.9.x.
- [ ] A JDK is available. The project builds with the bundled JDK at
      `portable-dist\jre` (contains `javac`). Set `JAVA_HOME` to it for Maven.

---

## Step-by-step checklist

### Step 1 — Check for updates on GitHub
- [ ] Run the update checker:
      ```powershell
      .\check-update.ps1
      ```
      It compares the bundled version (from `portable-dist\StudioBridge-X.Y.Z.jar`)
      with the latest GitHub release tag.
- [ ] Read the result:
      - `OK - You are up to date` → **stop here**, nothing to do (exit).
      - `UPDATE AVAILABLE: X.Y.Z -> A.B.C` → continue with Step 2.
      - `ERROR ...` → network/API problem; retry or proceed manually by visiting
        the [releases page](https://github.com/Rdiger-36/StudioBridge/releases).

### Step 2 — Fetch the new source code
- [ ] Create a temp working copy of the upstream repository:
      ```powershell
      $src = Join-Path $env:TEMP "StudioBridge-update-src"
      if (Test-Path $src) { Remove-Item $src -Recurse -Force }
      git clone --depth 1 https://github.com/Rdiger-36/StudioBridge.git $src
      ```
- [ ] (Optional) If the new release is a tag, check it out:
      ```powershell
      git -C $src fetch --tags --depth 1 origin tag v.<NEW_VERSION>
      git -C $src checkout v.<NEW_VERSION>
      ```
      Replace `<NEW_VERSION>` with the real tag (e.g. `v.2.1.4`).

### Step 3 — Review what changed
- [ ] Inspect the changelog / diff to understand the update:
      ```powershell
      git -C $src log --oneline -15
      Get-ChildItem $src\src -Recurse -File | Select-Object FullName
      ```
- [ ] Check the version was bumped in the upstream `pom.xml`
      (`<version>...`) and in `MainMenu.java`
      (`public static String version = "..."`).

### Step 4 — Re-apply the project-specific patch (persistent folder)
> ⚠️ **IMPORTANT:** The upstream code does **not** create the persistent data
> folder on startup. This project adds that behaviour. You must re-apply it to
> the fresh source or the rebuild will lose it.

- [ ] Copy the fresh source into the workspace (replacing the old one):
      ```powershell
      $dest = "c:\Users\scheianu\Desktop\Proiecte cod\Bambu_lab\StudioBridge-src"
      if (Test-Path $dest) { Remove-Item $dest -Recurse -Force }
      New-Item -ItemType Directory -Path $dest | Out-Null
      Get-ChildItem $src -Force | Where-Object { $_.Name -ne '.git' } |
          Copy-Item -Destination $dest -Recurse -Force
      ```
- [ ] Edit `StudioBridge-src\src\main\java\rdiger36\StudioBridge\gui\MainMenu.java`:

  **(a)** In `main(String[] args)`, right after `migrateLegacyProfilesPathSetting();`
  add a call to `ensurePersistentDirectories();` so it runs on every start
  (both GUI and `--sendonly` mode):
  ```java
  migrateOldDataDirectory();
  Config.loadAppSettings();
  migrateLegacyProfilesPathSetting();
  ensurePersistentDirectories();
  ```

  **(b)** Add the method after `mergeDirectories(...)`:
  ```java
  /**
   * Creates the application's persistent data directory and the profiles
   * sub-directory on startup (first run). This guarantees that the folder
   * exists even before the user saves anything, so that on the next start
   * the application can load the stored settings and printer profiles and
   * remember them.
   */
  private static void ensurePersistentDirectories() {
      try {
          File dataDir = new File(savePath);
          if (!dataDir.exists() && !dataDir.mkdirs()) {
              System.err.println("Warning! Could not create the persistent data directory: " + savePath);
          }
          File profilesDir = new File(ProfilesDir);
          if (!profilesDir.exists() && !profilesDir.mkdirs()) {
              System.err.println("Warning! Could not create the profiles directory: " + ProfilesDir);
          }
      } catch (Exception e) {
          System.err.println("Warning! Could not create the StudioBridge persistent data directory: " + savePath);
          e.printStackTrace();
      }
  }
  ```
- [ ] Confirm there are no compile errors (IDE / `get_errors` on the file).

### Step 5 — Build the new jar
- [ ] Build the fat jar with Maven (bundled JDK 11 as JAVA_HOME):
      ```powershell
      $env:JAVA_HOME = "c:\Users\scheianu\Desktop\Proiecte cod\Bambu_lab\portable-dist\jre"
      $mvn = "$env:LOCALAPPDATA\Programs\apache-maven-3.9.9\bin\mvn.cmd"
      & $mvn -f "c:\Users\scheianu\Desktop\Proiecte cod\Bambu_lab\StudioBridge-src\pom.xml" clean package
      ```
- [ ] Expected output file:
      `StudioBridge-src\target\StudioBridge-<VERSION>-jar-with-dependencies.jar`
      (this is the **complete bundle** — all dependencies included).

### Step 6 — Deploy to portable-dist
- [ ] Replace the old jar with the new one:
      ```powershell
      $root = "c:\Users\scheianu\Desktop\Proiecte cod\Bambu_lab"
      # remove old version jar(s)
      Get-ChildItem "$root\portable-dist" -Filter "StudioBridge-*.jar" | Remove-Item -Force
      Copy-Item "$root\StudioBridge-src\target\StudioBridge-<VERSION>-jar-with-dependencies.jar" `
                "$root\portable-dist\StudioBridge-<VERSION>.jar"
      ```

### Step 7 — Update the launcher scripts
- [ ] `portable-dist\StudioBridge.bat`: change the jar name to the new version:
      ```
      "%JAVA_HOME%\bin\java.exe" -jar "%~dp0StudioBridge-<VERSION>.jar" %*
      ```
- [ ] `Launch-StudioBridge.bat`: update the `JAR_FILE`, `JAR_URL` and echo texts
      to the new version. Use the release download URL pattern:
      ```
      https://github.com/Rdiger-36/StudioBridge/releases/download/v.<VERSION>/StudioBridge-<VERSION>.jar
      ```

### Step 8 — Update the README
- [ ] Bump every `v2.x.y` / `StudioBridge-x.y.z` reference in `README.md` to the new version.
- [ ] If the supported-printer table or arguments changed upstream, sync them from the
      upstream `README.md` (`StudioBridge-src\README.md`).

### Step 9 — Verify the new bundle
- [ ] Version check (must print the new version):
      ```powershell
      & "portable-dist\jre\bin\java.exe" -jar "portable-dist\StudioBridge-<VERSION>.jar" --help
      ```
- [ ] Persistent folder creation on a fresh run (uses a temp home so the real
      one is untouched):
      ```powershell
      $testHome = Join-Path $env:TEMP "sb-update-test-home"
      if (Test-Path $testHome) { Remove-Item $testHome -Recurse -Force }
      New-Item -ItemType Directory -Path $testHome | Out-Null
      & "portable-dist\jre\bin\java.exe" "-Duser.home=$testHome" `
        -jar "portable-dist\StudioBridge-<VERSION>.jar" --sendonly --noupdate
      Get-ChildItem $testHome -Recurse -Force | Select-Object FullName
      Remove-Item $testHome -Recurse -Force
      ```
      Expected: `<home>\.studio-bridge` and `<home>\.studio-bridge\Profiles` exist.
- [ ] (Optional) Run `.\check-update.ps1` again — it should now report up to date.

### Step 10 — Clean up
- [ ] Delete the temp clone:
      ```powershell
      Remove-Item (Join-Path $env:TEMP "StudioBridge-update-src") -Recurse -Force
      ```
- [ ] Remove the `StudioBridge-src\target` build output if you want a clean project:
      ```powershell
      Remove-Item "c:\Users\scheianu\Desktop\Proiecte cod\Bambu_lab\StudioBridge-src\target" -Recurse -Force
      ```

---

## Version locations to keep in sync (when bumping)
| File | Where |
|---|---|
| `StudioBridge-src\pom.xml` | `<version>X.Y.Z</version>` |
| `StudioBridge-src\...\gui\MainMenu.java` | `public static String version = "xyz"` (no dots) |
| `portable-dist\StudioBridge-X.Y.Z.jar` | deployed jar filename |
| `portable-dist\StudioBridge.bat` | jar filename |
| `Launch-StudioBridge.bat` | `JAR_FILE`, `JAR_URL`, echo texts |
| `README.md` | version references |

> Tip: after finishing, all todo boxes above should be ticked (`[x]`).