@www.hyperlinks.space/program-kit 1.2.3

package/windows/cleanup-legacy-appdata-installs.ps1

@@ -0,0 +1,91 @@
+# Remove leftover per-user installs under %LOCALAPPDATA%\Programs\ and updater sidecars.
+# Older builds often installed to AppData while current NSIS uses perMachine -> Program Files.
+#
+# Usage (from app/):
+#   powershell -ExecutionPolicy Bypass -File .\windows\cleanup-legacy-appdata-installs.ps1          # list only
+#   powershell -ExecutionPolicy Bypass -File .\windows\cleanup-legacy-appdata-installs.ps1 -Force   # delete
+# If removal fails with "in use", close the app or run with -KillAppProcesses (stops exes under those folders).
+#
+param(
+  [switch]$Force,
+  [switch]$KillAppProcesses
+)
+
+$ErrorActionPreference = "Continue"
+
+$legacyDirPatterns = @(
+  "Hyperlinks Space App"
+  "HyperlinksSpaceApp"
+  "hyperlinks-space-app"
+  "HyperlinksSpaceApp*"
+)
+
+function Test-LegacyDirName([string]$name) {
+  foreach ($p in $legacyDirPatterns) {
+    if ($p.EndsWith("*")) {
+      $prefix = $p.TrimEnd("*")
+      if ($name.StartsWith($prefix)) { return $true }
+    } elseif ($name -eq $p) { return $true }
+  }
+  return $false
+}
+
+$candidates = @()
+$programsRoot = "$env:LOCALAPPDATA\Programs"
+if (Test-Path -LiteralPath $programsRoot) {
+  Get-ChildItem -LiteralPath $programsRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+    if (Test-LegacyDirName $_.Name) { $candidates += $_.FullName }
+  }
+}
+
+$extra = @(
+  "$env:LOCALAPPDATA\expo-template-default-updater"
+  "$env:APPDATA\expo-template-default-updater"
+) | Where-Object { Test-Path -LiteralPath $_ }
+
+if ($candidates.Count -eq 0 -and $extra.Count -eq 0) {
+  Write-Host "No legacy per-user folders under LOCALAPPDATA\Programs (or updater sidecars) found."
+  exit 0
+}
+
+Write-Host "Legacy / AppData artifacts:"
+$candidates | ForEach-Object { Write-Host "  [dir] $_" }
+$extra | ForEach-Object { Write-Host "  [extra] $_" }
+
+if (-not $Force) {
+  Write-Host ""
+  Write-Host "Re-run with -Force to delete these paths."
+  exit 0
+}
+
+if ($KillAppProcesses -and $candidates.Count -gt 0) {
+  foreach ($dir in $candidates) {
+    $prefix = ($dir.TrimEnd("\")) + "\"
+    Get-Process -ErrorAction SilentlyContinue | Where-Object {
+      $_.Path -and $_.Path.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)
+    } | ForEach-Object {
+      Write-Host "Stopping process: $($_.Name) ($($_.Path))"
+      Stop-Process -Id $_.Id -Force -ErrorAction SilentlyContinue
+    }
+  }
+  Start-Sleep -Milliseconds 500
+}
+
+foreach ($p in $candidates) {
+  try {
+    Remove-Item -LiteralPath $p -Recurse -Force -ErrorAction Stop
+    Write-Host "Removed: $p"
+  } catch {
+    Write-Warning "Failed to remove $p : $_"
+  }
+}
+foreach ($p in $extra) {
+  try {
+    Remove-Item -LiteralPath $p -Recurse -Force -ErrorAction Stop
+    Write-Host "Removed: $p"
+  } catch {
+    Write-Warning "Failed to remove $p : $_"
+  }
+}
+
+Write-Host "Done."

package/windows/cleanup-legacy-windows-shortcuts.ps1

@@ -0,0 +1,46 @@
+# One-time cleanup: orphaned "Hyperlinks Space App" shortcuts (old product name; current is "Hyperlinks Space Program").
+# Run in PowerShell:  powershell -ExecutionPolicy Bypass -File windows/cleanup-legacy-windows-shortcuts.ps1
+# From repo app/:      powershell -ExecutionPolicy Bypass -File .\windows\cleanup-legacy-windows-shortcuts.ps1
+
+$ErrorActionPreference = "Continue"
+$legacy = "Hyperlinks Space App"
+
+$roots = @(
+  "$env:APPDATA\Microsoft\Windows\Start Menu\Programs",
+  "$env:ProgramData\Microsoft\Windows\Start Menu\Programs",
+  [Environment]::GetFolderPath("Desktop"),
+  "$env:PUBLIC\Desktop"
+) | Where-Object { $_ -and (Test-Path $_) }
+
+$removed = @()
+foreach ($root in $roots) {
+  Get-ChildItem -LiteralPath $root -Recurse -File -ErrorAction SilentlyContinue |
+    Where-Object {
+      $_.Extension -eq ".lnk" -and (
+        $_.Name -like "*$legacy*" -or
+        $_.DirectoryName -like "*$legacy*"
+      )
+    } |
+    ForEach-Object {
+      try {
+        Remove-Item -LiteralPath $_.FullName -Force
+        $removed += $_.FullName
+      } catch {
+        Write-Warning "Could not remove $($_.FullName): $_"
+      }
+    }
+}
+
+if ($removed.Count -eq 0) {
+  Write-Host "No legacy shortcuts matching '$legacy' were found under Start Menu / Desktop."
+} else {
+  Write-Host "Removed $($removed.Count) item(s):"
+  $removed | ForEach-Object { Write-Host "  $_" }
+}
+
+Write-Host ""
+Write-Host "If 'Hyperlinks Space App' still appears under Settings -> Apps, uninstall it there,"
+Write-Host "or run the current installer once (it also deletes legacy shortcuts in customInit)."
+Write-Host ""
+Write-Host "Old per-user installs may still exist under %LOCALAPPDATA%\Programs\. Run:"
+Write-Host "  powershell -ExecutionPolicy Bypass -File .\windows\cleanup-legacy-appdata-installs.ps1 -Force"

package/windows/cleanup.cjs

@@ -0,0 +1,200 @@
+/**
+ * Final layout under releases/builder/<build_id>/:
+ *   <productSlug>Installer_<stamp>.exe   (root — only distributable at top level)
+ *   dev/                                      (all other build artifacts)
+ * Staging (eb-output or releases/artifacts) is removed after this script runs.
+ */
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { RELEASE_BUILD_DEV_DIRNAME } = require("./build-layout.cjs");
+const { productSlug } = require("./product-brand.cjs");
+
+const appDir = path.join(__dirname, "..");
+const releasesDir = path.join(appDir, "releases");
+const legacyReleaseDir = path.join(appDir, "release");
+/** Per-build electron-builder staging (set by run-win-electron-builder / build-with-progress); else legacy global. */
+const artifactsDir = process.env.HSP_EB_OUTPUT?.trim()
+  ? path.resolve(appDir, process.env.HSP_EB_OUTPUT.trim())
+  : path.join(releasesDir, "artifacts");
+
+// build_MMDDYYYY_HHMM — optional override for CI (must match build_* pattern)
+const now = new Date();
+const pad = (n) => String(n).padStart(2, "0");
+const envBuildId = process.env.RELEASE_BUILD_ID?.trim();
+const defaultBuildName =
+  "build_" +
+  pad(now.getMonth() + 1) +
+  pad(now.getDate()) +
+  now.getFullYear() +
+  "_" +
+  pad(now.getHours()) +
+  pad(now.getMinutes());
+const buildName =
+  envBuildId && /^build_\d{8}_\d{4}$/.test(envBuildId) ? envBuildId : defaultBuildName;
+
+// releases/builder/build_MMDDYYYY_HHMM — installer only at root; everything else under dev/
+const buildDir = path.join(releasesDir, "builder", buildName);
+const devDir = path.join(buildDir, RELEASE_BUILD_DEV_DIRNAME);
+
+/** Required for electron-updater (GitHub) — must be uploaded next to the installer on each release. */
+const latestYmlName = "latest.yml";
+const zipLatestYmlName = "zip-latest.yml";
+const devArtifacts = [
+  "win-unpacked",
+  "builder-debug.yml",
+  "builder-effective-config.yaml",
+];
+
+function pickInstallerName() {
+  const files = fs.readdirSync(artifactsDir);
+  const installerRe = new RegExp(
+    `^${productSlug}Installer(?:_\\d{8}_\\d{4})?\\.exe$`,
+    "i",
+  );
+  const candidates = files.filter((f) => installerRe.test(f));
+  if (candidates.length === 0) return null;
+  // Prefer timestamped file if both legacy/static and stamped files exist.
+  candidates.sort((a, b) => b.length - a.length || a.localeCompare(b));
+  return candidates[0];
+}
+
+function pickZipName() {
+  const files = fs.readdirSync(artifactsDir);
+  const zipRe = new RegExp(`^${productSlug}_[\\d.]+\\.zip$`, "i");
+  const candidates = files.filter((f) => zipRe.test(f));
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => b.localeCompare(a));
+  return candidates[0];
+}
+
+function moveIfExists(src, dest) {
+  if (!fs.existsSync(src)) return false;
+  try {
+    fs.renameSync(src, dest);
+    console.log("Moved:", path.relative(artifactsDir, src));
+    return true;
+  } catch (e) {
+    try {
+      const stat = fs.statSync(src);
+      if (stat.isDirectory()) {
+        fs.cpSync(src, dest, { recursive: true });
+        fs.rmSync(src, { recursive: true });
+      } else {
+        fs.copyFileSync(src, dest);
+        fs.unlinkSync(src);
+      }
+      console.log("Moved (copy+delete):", path.relative(artifactsDir, src));
+      return true;
+    } catch (e2) {
+      console.warn("Could not move", src, e2.message);
+      return false;
+    }
+  }
+}
+
+/** Anything electron-builder left behind (zip blockmaps, nsis temps, etc.) → dev/ */
+function moveRemainingStagingToDev() {
+  if (!fs.existsSync(artifactsDir)) return;
+  let names;
+  try {
+    names = fs.readdirSync(artifactsDir);
+  } catch (_) {
+    return;
+  }
+  for (const name of names) {
+    const src = path.join(artifactsDir, name);
+    const dest = path.join(devDir, name);
+    if (!fs.existsSync(src)) continue;
+    try {
+      if (fs.existsSync(dest)) {
+        fs.rmSync(dest, { recursive: true, force: true });
+      }
+    } catch (e) {
+      console.warn("Could not clear dev target", dest, e?.message || e);
+      continue;
+    }
+    moveIfExists(src, dest);
+  }
+}
+
+const exeName = pickInstallerName();
+if (!exeName) {
+  console.warn(`No installer in ${path.relative(appDir, artifactsDir)}/. Run electron-builder first.`);
+  process.exit(1);
+}
+const exeSrc = path.join(artifactsDir, exeName);
+
+fs.mkdirSync(devDir, { recursive: true });
+
+// Installer at build folder root only
+const exeDest = path.join(buildDir, exeName);
+moveIfExists(exeSrc, exeDest);
+
+const latestSrc = path.join(artifactsDir, latestYmlName);
+const latestDest = path.join(devDir, latestYmlName);
+if (!moveIfExists(latestSrc, latestDest)) {
+  console.warn(`No latest.yml in ${path.relative(appDir, artifactsDir)}/ — generating one for electron-updater.`);
+}
+
+/** NSIS update metadata; electron-builder sometimes omits this unless publishing. */
+function writeLatestYmlForExe(exePath, ymlPath) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(appDir, "package.json"), "utf8"));
+  const version = String(pkg.version ?? "0.0.0");
+  const exeFileName = path.basename(exePath);
+  const buf = fs.readFileSync(exePath);
+  const sha512 = crypto.createHash("sha512").update(buf).digest("base64");
+  const size = buf.length;
+  const releaseDate = new Date().toISOString();
+  const yml =
+    `version: ${version}\n` +
+    `files:\n` +
+    `  - url: ${exeFileName}\n` +
+    `    sha512: ${sha512}\n` +
+    `    size: ${size}\n` +
+    `path: ${exeFileName}\n` +
+    `sha512: ${sha512}\n` +
+    `releaseDate: '${releaseDate}'\n`;
+  fs.writeFileSync(ymlPath, yml, "utf8");
+  console.log("Wrote:", path.relative(appDir, ymlPath));
+}
+
+if (fs.existsSync(exeDest) && !fs.existsSync(latestDest)) {
+  writeLatestYmlForExe(exeDest, latestDest);
+}
+
+const zipName = pickZipName();
+const zipDest = zipName ? path.join(devDir, zipName) : null;
+const zipLatestDest = path.join(devDir, zipLatestYmlName);
+if (zipName) {
+  moveIfExists(path.join(artifactsDir, zipName), zipDest);
+}
+if (zipDest && fs.existsSync(zipDest)) {
+  writeLatestYmlForExe(zipDest, zipLatestDest);
+}
+
+// Move optional/debug artifacts into dev/
+for (const name of devArtifacts) {
+  const src = path.join(artifactsDir, name);
+  const dest = path.join(devDir, name);
+  moveIfExists(src, dest);
+}
+const blockmapName = `${exeName}.blockmap`;
+moveIfExists(path.join(artifactsDir, blockmapName), path.join(devDir, blockmapName));
+
+moveRemainingStagingToDev();
+
+// Remove electron-builder staging (eb-output or legacy releases/artifacts).
+try {
+  if (fs.existsSync(legacyReleaseDir)) {
+    fs.rmSync(legacyReleaseDir, { recursive: true, force: true });
+    console.log("Removed release/ (legacy)");
+  }
+  if (fs.existsSync(artifactsDir)) {
+    fs.rmSync(artifactsDir, { recursive: true, force: true });
+    const label = process.env.HSP_EB_OUTPUT?.trim() ? "eb-output" : "releases/artifacts";
+    console.log(`Removed ${label}/`);
+  }
+} catch (_) {}
+
+console.log("Output:", path.join("releases", "builder", buildName));

package/windows/embed-windows-exe-icon.cjs

@@ -0,0 +1,55 @@
+/**
+ * Embed assets/icon.ico into the Windows app .exe using electron-builder's app-builder `rcedit`
+ * (same stack as WinPackager.signAndEditResources). Do not use the `rcedit` npm wrapper here:
+ * it often lacks bin/rcedit.exe or uses an older binary that mishandles large PNG-based .ico files.
+ */
+const fs = require("fs");
+const path = require("path");
+const { executeAppBuilder } = require("builder-util");
+
+async function embedIconWithAppBuilder(exePath, iconPath) {
+  const rceditArgs = [exePath, "--set-icon", path.resolve(iconPath)];
+  await executeAppBuilder(["rcedit", "--args", JSON.stringify(rceditArgs)], undefined, {}, 3);
+}
+
+/**
+ * @param {{ appOutDir: string, projectDir: string, productFilename?: string }} opts
+ */
+async function embedWindowsExeIcon(opts) {
+  if (process.platform !== "win32") return;
+  if (process.env.CSC_LINK || process.env.WIN_CSC_LINK) {
+    console.log("[embed-windows-exe-icon] skip: CSC_LINK / WIN_CSC_LINK set (would break signature)");
+    return;
+  }
+  const icon = path.resolve(opts.projectDir, "assets", "icon.ico");
+  if (!fs.existsSync(icon)) {
+    console.warn(`[embed-windows-exe-icon] skip: missing ${icon}`);
+    return;
+  }
+  let exe;
+  if (opts.productFilename) {
+    exe = path.join(opts.appOutDir, `${opts.productFilename}.exe`);
+  } else {
+    let names;
+    try {
+      names = fs.readdirSync(opts.appOutDir);
+    } catch (e) {
+      console.warn(`[embed-windows-exe-icon] skip: cannot read ${opts.appOutDir}: ${e?.message || e}`);
+      return;
+    }
+    const exes = names.filter((f) => f.endsWith(".exe") && !/uninstall/i.test(f));
+    if (exes.length !== 1) {
+      console.warn(`[embed-windows-exe-icon] skip: expected one app .exe in ${opts.appOutDir}, got: ${exes.join(", ")}`);
+      return;
+    }
+    exe = path.join(opts.appOutDir, exes[0]);
+  }
+  if (!fs.existsSync(exe)) {
+    console.warn(`[embed-windows-exe-icon] skip: exe not found ${exe}`);
+    return;
+  }
+  await embedIconWithAppBuilder(exe, icon);
+  console.log(`[embed-windows-exe-icon] app-builder rcedit: ${icon} -> ${exe}`);
+}
+
+module.exports = { embedWindowsExeIcon, embedIconWithAppBuilder };

package/windows/extractAppPackage.nsh

@@ -0,0 +1,150 @@
+; Shadow of app-builder-lib templates/nsis/include/extractAppPackage.nsh
+; (buildResources is searched before the bundled template — see NSIS !addincludedir order.)
+;
+; Changes: Call HspKillBeforeCopy before every CopyFiles (and each retry) so taskkill + wait
+; runs after uninstall/old files, not only in customCheckAppRunning. More automatic retries
+; before the "cannot close app" dialog. Sync with upstream when upgrading electron-builder.
+; HspInstallStepStatus: step 3 = decompress start, step 4 = payload on disk (must match HSP_INSTALL_STEP_TOTAL in installer-hooks.nsi).
+
+!macro extractEmbeddedAppPackage
+  !ifdef COMPRESS
+    SetCompress off
+  !endif
+
+  Var /GLOBAL packageArch
+  
+  !insertmacro identify_package
+  !insertmacro compute_files_for_current_arch
+
+  !ifdef COMPRESS
+    SetCompress "${COMPRESS}"
+  !endif
+
+  !insertmacro decompress
+  !insertmacro custom_files_post_decompression
+!macroend
+
+!macro identify_package 
+  !ifdef APP_32
+    StrCpy $packageArch "32"
+  !endif
+  !ifdef APP_64
+    ${if} ${RunningX64}
+    ${OrIf} ${IsNativeARM64}
+      StrCpy $packageArch "64"
+    ${endif}
+  !endif
+  !ifdef APP_ARM64
+    ${if} ${IsNativeARM64}
+      StrCpy $packageArch "ARM64"
+    ${endif}
+  !endif
+!macroend
+
+!macro compute_files_for_current_arch
+  ${if} $packageArch == "ARM64"
+    !ifdef APP_ARM64
+      !insertmacro arm64_app_files
+    !endif
+  ${elseif} $packageArch == "64"
+    !ifdef APP_64
+      !insertmacro x64_app_files
+    !endif
+  ${else}
+    !ifdef APP_32
+      !insertmacro ia32_app_files
+    !endif
+  ${endIf}
+!macroend
+
+!macro custom_files_post_decompression
+  ${if} $packageArch == "ARM64"
+    !ifmacrodef customFiles_arm64
+      !insertmacro customFiles_arm64
+    !endif
+  ${elseif} $packageArch == "64"
+    !ifmacrodef customFiles_x64
+      !insertmacro customFiles_x64
+    !endif
+  ${else}
+    !ifmacrodef customFiles_ia32
+      !insertmacro customFiles_ia32
+    !endif
+  ${endIf}
+!macroend
+
+!macro arm64_app_files
+  File /oname=$PLUGINSDIR\app-arm64.${COMPRESSION_METHOD} "${APP_ARM64}"
+!macroend
+
+!macro x64_app_files
+  File /oname=$PLUGINSDIR\app-64.${COMPRESSION_METHOD} "${APP_64}"
+!macroend
+
+!macro ia32_app_files
+  File /oname=$PLUGINSDIR\app-32.${COMPRESSION_METHOD} "${APP_32}"
+!macroend
+
+!macro decompress
+  !ifdef ZIP_COMPRESSION
+    !insertmacro HspInstallStepStatus 3
+    nsisunz::Unzip "$PLUGINSDIR\app-$packageArch.zip" "$INSTDIR"
+    Pop $R0
+    StrCmp $R0 "success" +3
+      MessageBox MB_OK|MB_ICONEXCLAMATION "$(decompressionFailed)$\n$R0"
+      Quit
+    !insertmacro HspInstallStepStatus 4
+  !else
+    !insertmacro extractUsing7za "$PLUGINSDIR\app-$packageArch.7z"
+  !endif
+!macroend
+
+!macro extractUsing7za FILE
+  !insertmacro HspInstallStepStatus 3
+  Push $OUTDIR
+  CreateDirectory "$PLUGINSDIR\7z-out"
+  ClearErrors
+  SetOutPath "$PLUGINSDIR\7z-out"
+  Nsis7z::Extract "${FILE}"
+  Pop $R0
+  SetOutPath $R0
+
+  # Retry counter
+  StrCpy $R1 0
+
+  LoopExtract7za:
+    IntOp $R1 $R1 + 1
+    Call HspKillBeforeCopy
+
+    # Attempt to copy files in atomic way
+    CopyFiles /SILENT "$PLUGINSDIR\7z-out\*" $OUTDIR
+    IfErrors 0 DoneExtract7za
+
+    DetailPrint `Can't modify "${PRODUCT_NAME}"'s files.`
+    ${if} $R1 < 15
+      # Automatic retries (same work as user clicking Retry: kill + wait + copy again).
+      Goto RetryExtract7za
+    ${else}
+      MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION "$(appCannotBeClosed)" /SD IDRETRY IDCANCEL AbortExtract7za
+    ${endIf}
+
+    # As an absolutely last resort after a few automatic attempts and user
+    # intervention - we will just overwrite everything with `Nsis7z::Extract`
+    # even though it is not atomic and will ignore errors.
+
+    # Clear the temporary folder first to make sure we don't use twice as
+    # much disk space.
+    RMDir /r "$PLUGINSDIR\7z-out"
+
+    Nsis7z::Extract "${FILE}"
+    Goto DoneExtract7za
+
+  AbortExtract7za:
+    Quit
+
+  RetryExtract7za:
+    Goto LoopExtract7za
+
+  DoneExtract7za:
+    !insertmacro HspInstallStepStatus 4
+!macroend

package/windows/forge/README.md

@@ -0,0 +1,41 @@
+# Electron Forge (Windows)
+
+Forge config and helpers live under `windows/forge/`.
+
+This packages your existing Electron main process:
+
+- `../build.cjs`
+
+## Configuration
+
+Forge loads config via `package.json` → `config.forge` → `./windows/forge/forge.config.js` (no root `forge.config.js` wrapper).
+
+## Build
+
+From `app/`, run:
+
+```bash
+npm run make:win:forge
+```
+
+This will:
+
+1. Build the Expo web `dist/`
+2. Run Electron Forge `make` (Windows NSIS + zip makers)
+3. Run `windows/forge-cleanup.cjs` into `releases/forge/build_<stamp>_forge/`
+
+## Release layout (mirrors builder; tag ends with `_forge`)
+
+Each Forge build folder:
+
+- `releases/forge/build_MMDDYYYY_HHMM_forge/HyperlinksSpaceProgramInstaller_<stamp>.exe` (root only)
+- `releases/forge/build_MMDDYYYY_HHMM_forge/dev/latest.yml`
+- `releases/forge/build_MMDDYYYY_HHMM_forge/dev/HyperlinksSpaceProgram_<version>.zip`
+- `releases/forge/build_MMDDYYYY_HHMM_forge/dev/zip-latest.yml`
+- `releases/forge/build_MMDDYYYY_HHMM_forge/dev/` — unpacked app, blockmaps, etc.
+
+CI flattens the four release assets into `releases/electron/build_<timestamp>_forge/` for GitHub upload.
+
+## Notes
+
+The Forge NSIS maker reads `package.json` `build` (app-builder-lib), so behavior can align with electron-builder.