@webprodigies/morphite 0.2.2 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
 # Morphite
 
-Install or update Morphite on your Mac:
+Install or update Morphite on your Mac or Windows PC:
 
 ```sh
 npx @webprodigies/morphite
@@ -8,4 +8,6 @@ npx @webprodigies/morphite
 
 The installer checks your Mac, downloads the latest release for Apple silicon or Intel, verifies its SHA-256 checksum, puts the app in Applications and opens it. Run the same command again to update. Your projects and settings live outside the app and are never changed by the installer.
 
-Requires macOS 12 or later and Node.js 18 or later. Windows and Linux are on the way.
+On Windows it installs Morphite for you alone in `%LOCALAPPDATA%\Programs` (no administrator needed), adds it to the Start menu and opens it.
+
+Requires macOS 12 or later, or Windows 10 (version 1803) or later, and Node.js 18 or later. Linux is on the way.

package/app-update.mjs

@@ -0,0 +1,281 @@
+/** SOURCE OF TRUTH KEYWORDS: appUpdateSteps, APP_SWAP, SWAP_HELPER_SCRIPT, verifyApp, STAGE_PREFIX
+ * WHAT: The steps that replace an installed Morphite with a release, for the terminal installer and
+ *   the app's own Update alike: read the release manifest, download the zip for this CPU while
+ *   measuring its SHA-256, unpack it with ditto, check the unpacked app (bundle id, version,
+ *   signature), clear the download mark, and swap it in by renames: the installed app is set aside,
+ *   the new one renamed into place, and on any failure the installed app is put back.
+ * WHY: Both paths must trust and replace an app the same way. After the app quits nothing of it may
+ *   run, and packaged Electron cannot run as Node (hardenPackagedElectron's RunAsNode fuse), so the
+ *   app's swap runs as SWAP_HELPER_SCRIPT under /bin/sh; it repeats swapApps's steps and is tested
+ *   against the same cases. Its inputs are positional arguments; no path is ever put into its text.
+ * WHERE: bin/morphite.mjs (installer) and src/desktop/updates/release-install.ts (STAGED_UPDATE)
+ *   import these; on Windows the swap helper is WINDOWS_SWAP_HELPER_SCRIPT and the unpacking and
+ *   checks are windows.mjs's (WINDOWS_INSTALL); manifest.mjs owns the release format. Plain JavaScript: the installer has no
+ *   build step or dependencies.
+ */
+import { createHash } from 'node:crypto'
+import { createReadStream, createWriteStream } from 'node:fs'
+import { execFile } from 'node:child_process'
+import { rename, stat, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { once } from 'node:events'
+import { promisify } from 'node:util'
+import { INSTALL_MANIFEST_FILE, latestManifestUrl, parseInstallManifest, releaseFileUrl } from './manifest.mjs'
+
+const run = promisify(execFile)
+/** Folders Morphite creates beside an installed app while updating it; only these are cleaned up. */
+export const STAGE_PREFIX = '.morphite-update-'
+/** The file inside such a folder that proves Morphite made it. */
+export const STAGE_MARK = 'morphite-update.json'
+
+export async function fetchWithRetry(url, { attempts = 3, userAgent = '@webprodigies/morphite installer', signal } = {}) {
+  let failure
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const response = await fetch(url, { headers: { 'user-agent': userAgent }, redirect: 'follow', signal })
+      if (response.status === 404) return response
+      if (!response.ok) throw Error(`HTTP ${response.status}`)
+      return response
+    } catch (error) {
+      if (signal?.aborted) throw error
+      failure = error
+      await new Promise((resolve) => setTimeout(resolve, 600 * attempt))
+    }
+  }
+  throw Error(`Could not reach GitHub (${failure?.message ?? 'network error'}). Check your connection and run the command again.`)
+}
+
+/** The checked manifest of the newest release, or of the release in the local folder `from`. */
+export async function readManifest(from, options) {
+  if (from) return parseInstallManifest(JSON.parse(await readFile(join(from, INSTALL_MANIFEST_FILE), 'utf8')))
+  const response = await fetchWithRetry(latestManifestUrl(), options)
+  if (response.status === 404) throw Error('No Morphite release is available yet. Try again soon.')
+  return parseInstallManifest(await response.json())
+}
+
+/** Downloads (or copies from `from`) one archive to `destination`, measuring it as it arrives. */
+export async function downloadArchive(manifest, archive, destination, { from, progress, signal, ...options } = {}) {
+  const hash = createHash('sha256')
+  let received = 0
+  const report = () => progress?.(received / archive.size, received)
+  const output = createWriteStream(destination, { mode: 0o600 })
+  const write = async (chunk) => {
+    hash.update(chunk)
+    received += chunk.length
+    if (received > archive.size) throw Error('The download is larger than the release says. Nothing was installed.')
+    if (!output.write(chunk)) await once(output, 'drain')
+  }
+  const timer = progress ? setInterval(report, 120) : undefined
+  try {
+    if (from) {
+      for await (const chunk of createReadStream(join(from, archive.file), { signal })) await write(chunk)
+    } else {
+      const response = await fetchWithRetry(releaseFileUrl(manifest.tag, archive.file), { ...options, signal })
+      if (!response.ok || !response.body) throw Error(`The release file is unavailable (HTTP ${response.status}).`)
+      for await (const chunk of response.body) await write(chunk)
+    }
+    output.end()
+    await once(output, 'finish')
+  } finally {
+    clearInterval(timer)
+    output.destroy()
+  }
+  report()
+  return { path: destination, sha256: hash.digest('hex'), size: received }
+}
+export const archiveMatches = (file, archive) => file.size === archive.size && file.sha256 === archive.sha256
+
+/** Unpacks a release zip (made with ditto --keepParent) into `folder`. */
+export async function unpackApp(zip, folder) {
+  await run('/usr/bin/ditto', ['-x', '-k', zip, folder])
+}
+const infoValue = (app, key) =>
+  run('/usr/bin/plutil', ['-extract', key, 'raw', '-o', '-', join(app, 'Contents/Info.plist')]).then(
+    (result) => result.stdout.trim(),
+    () => null
+  )
+export class AppCheckError extends Error {
+  constructor(reason, message) {
+    super(message)
+    this.reason = reason
+  }
+}
+/** Throws an AppCheckError unless `app` is the expected Morphite build with an intact signature. */
+export async function verifyApp(app, { bundleId, version }) {
+  if ((await infoValue(app, 'CFBundleIdentifier')) !== bundleId)
+    throw new AppCheckError('bundle-id', 'The downloaded app isn’t the expected Morphite build.')
+  if ((await infoValue(app, 'CFBundleShortVersionString')) !== version)
+    throw new AppCheckError('version', 'The downloaded app isn’t the version the release names.')
+  await run('/usr/bin/codesign', ['--verify', '--deep', '--strict', app]).catch(() => {
+    throw new AppCheckError('signature', 'The downloaded app failed its signature check.')
+  })
+}
+/** A file fetched by Morphite carries no download mark; one is cleared defensively all the same. */
+export async function clearQuarantine(app) {
+  await run('/usr/bin/xattr', ['-dr', 'com.apple.quarantine', app]).catch(() => undefined)
+}
+
+/** APP_SWAP: sets every installed copy aside (aside(index)), renames `candidate` to `destination`
+ *  and returns what was set aside; on any failure puts every copy back and throws. */
+export async function swapApps(installed, candidate, destination, aside) {
+  const replaced = []
+  try {
+    for (const previous of installed) {
+      const moved = aside(replaced.length)
+      await rename(previous, moved)
+      replaced.push([previous, moved])
+    }
+    if (await stat(destination).catch(() => null)) throw Error(`${destination} already exists and isn’t Morphite.`)
+    await rename(candidate, destination)
+    return replaced
+  } catch (error) {
+    for (const [original, moved] of replaced.reverse()) await rename(moved, original).catch(() => undefined)
+    throw error
+  }
+}
+
+/** APP_SWAP for the app's own Update, run detached by /bin/sh after Morphite starts quitting:
+ *    sh -c SWAP_HELPER_SCRIPT morphite-update PID CURRENT STAGED ASIDE DESTINATION REOPEN ELEVATE
+ *  Waits (up to 10 minutes) for PID to exit, sets CURRENT aside to ASIDE, renames STAGED to
+ *  DESTINATION, puts CURRENT back on any failure, clears the download mark and, with REOPEN=1,
+ *  opens whichever app is in place. With ELEVATE=1 only the swap runs through macOS's administrator
+ *  prompt: the fixed AppleScript passes this same script (MORPHITE_SWAP_SCRIPT) and the paths as
+ *  arguments, quoted by AppleScript's `quoted form of`. Exit codes: 0 updated, 3 Morphite did not
+ *  quit, 4 nothing staged, 5 aside taken, 6 could not set aside, 7 rolled back, 8 not authorized. */
+export const SWAP_HELPER_SCRIPT = String.raw`
+set -u
+say() { printf '%s %s\n' "$(/bin/date '+%Y-%m-%dT%H:%M:%S')" "$1"; }
+swap() {
+  current=$1 staged=$2 aside=$3 destination=$4
+  if [ ! -d "$staged" ]; then say "The prepared update is missing. Nothing was changed."; return 4; fi
+  if [ -e "$aside" ]; then say "The previous app's place is taken. Nothing was changed."; return 5; fi
+  if ! /bin/mv "$current" "$aside"; then say "The installed app couldn't be set aside. Nothing was changed."; return 6; fi
+  if [ -e "$destination" ] || ! /bin/mv "$staged" "$destination"; then
+    /bin/mv "$aside" "$current" || say "The previous app is at $aside."
+    say "The update couldn't be moved into place; the previous app was put back."
+    return 7
+  fi
+  /usr/bin/xattr -dr com.apple.quarantine "$destination" 2>/dev/null
+  return 0
+}
+if [ "$1" = swap ]; then shift; swap "$@"; exit $?; fi
+pid=$1 current=$2 staged=$3 aside=$4 destination=$5 reopen=$6 elevate=$7
+waited=0
+while /bin/kill -0 "$pid" 2>/dev/null; do
+  if [ "$waited" -ge 1200 ]; then say "Morphite didn't quit. Nothing was changed."; exit 3; fi
+  /bin/sleep 0.5
+  waited=$((waited + 1))
+done
+if [ "$elevate" = 1 ]; then
+  /usr/bin/osascript \
+    -e 'on run argv' \
+    -e 'do shell script "/bin/sh -c " & quoted form of (item 1 of argv) & " morphite-update swap " & quoted form of (item 2 of argv) & " " & quoted form of (item 3 of argv) & " " & quoted form of (item 4 of argv) & " " & quoted form of (item 5 of argv) with prompt "Morphite needs your permission to finish updating." with administrator privileges' \
+    -e 'end run' "$MORPHITE_SWAP_SCRIPT" "$current" "$staged" "$aside" "$destination"
+  result=$?
+  [ "$result" -eq 0 ] || { say "The update wasn't authorized or couldn't be moved into place. The previous app is in place."; result=8; }
+else
+  swap "$current" "$staged" "$aside" "$destination"
+  result=$?
+fi
+if [ "$result" -eq 0 ]; then say "Updated $destination."; opened=$destination; else opened=$current; fi
+if [ "$reopen" = 1 ]; then /usr/bin/open "$opened" || say "Morphite couldn't be reopened."; fi
+exit "$result"
+`
+
+/** APP_SWAP for the app's own Update on Windows: the same steps as SWAP_HELPER_SCRIPT, as a PowerShell
+ *  script started detached while Morphite quits (a running exe cannot be replaced). Its inputs are
+ *  environment variables, never put into its text: MORPHITE_SWAP_PID, _CURRENT, _STAGED, _ASIDE,
+ *  _DESTINATION, _REOPEN and _LOG (the file its lines are added to). It waits (up to 10 minutes) for PID and then for every program still
+ *  running from CURRENT's folder (Morphite's helpers), sets CURRENT aside to ASIDE (retrying while
+ *  Windows briefly holds a file), renames STAGED to DESTINATION, puts CURRENT back on any failure
+ *  and, with REOPEN=1, starts <name>.exe in whichever folder is in place. Same exit codes; there is
+ *  no administrator step: a Windows install lives in the person's own Programs folder. */
+export const WINDOWS_SWAP_HELPER_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+Set-Location -LiteralPath $env:SystemRoot
+function Say($text) {
+  $line = '{0} {1}' -f (Get-Date -Format 's'), $text
+  # Straight to the console, never the pipeline: Swap's return value is its exit code alone.
+  if ($env:MORPHITE_SWAP_LOG) { Add-Content -LiteralPath $env:MORPHITE_SWAP_LOG -Value $line } else { [Console]::Out.WriteLine($line) }
+}
+$morphite = [int]$env:MORPHITE_SWAP_PID
+$current = $env:MORPHITE_SWAP_CURRENT; $staged = $env:MORPHITE_SWAP_STAGED; $aside = $env:MORPHITE_SWAP_ASIDE
+$destination = $env:MORPHITE_SWAP_DESTINATION; $reopen = $env:MORPHITE_SWAP_REOPEN
+$inside = $current.TrimEnd('\') + '\'
+$waited = 0
+while ($true) {
+  $open = @(Get-Process -Id $morphite -ErrorAction SilentlyContinue)
+  if (-not $open.Count) {
+    $open = @(Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -and $_.ExecutablePath.StartsWith($inside, [StringComparison]::OrdinalIgnoreCase) })
+    if (-not $open.Count) { break }
+  }
+  if ($waited -ge 1200) { Say "Morphite didn't quit. Nothing was changed."; exit 3 }
+  Start-Sleep -Milliseconds 500
+  $waited++
+}
+function Swap {
+  if (-not (Test-Path -LiteralPath $staged -PathType Container)) { Say 'The prepared update is missing. Nothing was changed.'; return 4 }
+  if (Test-Path -LiteralPath $aside) { Say "The previous app's place is taken. Nothing was changed."; return 5 }
+  $moved = $false
+  for ($try = 0; $try -lt 20 -and -not $moved; $try++) {
+    try { [IO.Directory]::Move($current, $aside); $moved = $true } catch { Start-Sleep -Milliseconds 500 }
+  }
+  if (-not $moved) { Say "The installed app couldn't be set aside. Nothing was changed."; return 6 }
+  try {
+    if (Test-Path -LiteralPath $destination) { throw 'taken' }
+    [IO.Directory]::Move($staged, $destination)
+    return 0
+  } catch {
+    try { [IO.Directory]::Move($aside, $current) } catch { Say "The previous app is at $aside." }
+    Say "The update couldn't be moved into place; the previous app was put back."
+    return 7
+  }
+}
+$result = Swap
+if ($result -eq 0) { Say "Updated $destination."; $opened = $destination } else { $opened = $current }
+if ($reopen -eq '1') {
+  $program = Join-Path $opened ((Split-Path -Leaf $destination) + '.exe')
+  try { Start-Process -FilePath $program -WorkingDirectory $opened } catch { Say "Morphite couldn't be reopened." }
+}
+exit $result
+`
+/** How the swap helper starts for `args` (PID CURRENT STAGED ASIDE DESTINATION REOPEN ELEVATE): the
+ *  /bin/sh script on macOS, spawned detached with its output in the log. On Windows a short hidden
+ *  PowerShell launcher that starts the helper with Start-Process and exits: a program Node starts on
+ *  Windows ends with its parent's job (and PowerShell cannot run detached, without a console), while
+ *  a program that one starts breaks away and outlives Morphite. The helper writes `log` itself. */
+export function swapHelperCommand(platform, args, env = process.env, log = '') {
+  if (platform !== 'win32')
+    return {
+      file: '/bin/sh',
+      args: ['-c', SWAP_HELPER_SCRIPT, 'morphite-update', ...args],
+      env: { PATH: '/usr/bin:/bin:/usr/sbin:/sbin', MORPHITE_SWAP_SCRIPT: SWAP_HELPER_SCRIPT }
+    }
+  const [pid, current, staged, aside, destination, reopen] = args
+  const variable = (name) => env[Object.keys(env).find((key) => key.toUpperCase() === name) ?? name]
+  const system32 = join(variable('SYSTEMROOT') || variable('WINDIR') || 'C:\\Windows', 'System32')
+  const powershell = join(system32, 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+  const encoded = (script) => Buffer.from(script, 'utf16le').toString('base64')
+  // Working from the system folder: a program working inside Morphite's folder keeps it from moving.
+  const launcher = "Start-Process -WindowStyle Hidden -WorkingDirectory $env:MORPHITE_SWAP_SYSTEM -FilePath $env:MORPHITE_SWAP_POWERSHELL -ArgumentList '-NoProfile','-NonInteractive','-ExecutionPolicy','Bypass','-EncodedCommand',$env:MORPHITE_SWAP_HELPER"
+  return {
+    file: powershell,
+    cwd: system32,
+    args: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded(launcher)],
+    // The reopened Morphite starts with Morphite's own environment.
+    env: {
+      ...env,
+      MORPHITE_SWAP_POWERSHELL: powershell,
+      MORPHITE_SWAP_SYSTEM: system32,
+      MORPHITE_SWAP_HELPER: encoded(WINDOWS_SWAP_HELPER_SCRIPT),
+      MORPHITE_SWAP_PID: pid,
+      MORPHITE_SWAP_CURRENT: current,
+      MORPHITE_SWAP_STAGED: staged,
+      MORPHITE_SWAP_ASIDE: aside,
+      MORPHITE_SWAP_DESTINATION: destination,
+      MORPHITE_SWAP_REOPEN: reopen,
+      MORPHITE_SWAP_LOG: log
+    }
+  }
+}

package/bin/morphite.mjs

@@ -1,25 +1,37 @@
 #!/usr/bin/env node
 /** SOURCE OF TRUTH KEYWORDS: terminalInstaller, installMorphite, INSTALLER_STEPS
- * WHAT: `npx @webprodigies/morphite` installs or updates the Mac app: checks the Mac, reads the
- *   latest release manifest, downloads the zip for this CPU with progress, checks its SHA-256,
- *   replaces the app in Applications and opens it. It prints a few quiet lines (INSTALLER_LOOK).
+ * WHAT: `npx @webprodigies/morphite` installs or updates Morphite on a Mac or a Windows PC: checks
+ *   the computer, reads the latest release manifest, downloads the zip for this computer with
+ *   progress, checks its SHA-256, replaces the app and opens it. It prints a few quiet lines
+ *   (INSTALLER_LOOK). Each OS supplies its own steps (macSteps below, windowsSteps from
+ *   ../windows.mjs); the flow between them is shared.
  * WHY: Until Morphite has a Developer ID, a browser download is stopped by Gatekeeper and people must
  *   allow it in Privacy & Security. A file fetched by this program is not marked as downloaded, so the
  *   verified app opens directly. Running the same command again is the update.
- * WHERE: ../manifest.mjs owns the release file format; scripts/release-publish.ts publishes releases;
- *   the desktop app's Update action opens this command in Terminal. User data lives outside the app
- *   bundle and is never touched here.
+ * WHERE: ../manifest.mjs owns the release file format and ../app-update.mjs the download, checks
+ *   and swap (appUpdateSteps), shared with the desktop app's own Update, which offers this command
+ *   only when it cannot prepare an update itself. scripts/release-publish.ts publishes releases.
+ *   User data lives outside the app and is never touched here.
  */
-import { createHash } from 'node:crypto'
-import { createWriteStream } from 'node:fs'
-import { access, constants, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, stat } from 'node:fs/promises'
+import { access, constants, lstat, mkdir, mkdtemp, readdir, rm } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
 import { homedir, platform, tmpdir, arch as nodeArch } from 'node:os'
 import { join, basename, dirname } from 'node:path'
-import { once } from 'node:events'
 import { createInterface } from 'node:readline'
 import { promisify } from 'node:util'
-import { INSTALL_MANIFEST_FILE, latestManifestUrl, parseInstallManifest, releaseFileUrl } from '../manifest.mjs'
+import { AppCheckError, archiveMatches, clearQuarantine, downloadArchive, readManifest, swapApps, unpackApp, verifyApp } from '../app-update.mjs'
+import { archiveTarget } from '../manifest.mjs'
+import {
+  openWindowsApp,
+  runningWindowsApps,
+  supportedWindows,
+  unpackWindowsApp,
+  verifyWindowsApp,
+  windowsAppInfo,
+  windowsPlaces,
+  windowsVersion,
+  writeStartMenuShortcut
+} from '../windows.mjs'
 
 const run = promisify(execFile)
 const args = process.argv.slice(2)
@@ -134,70 +146,108 @@ async function moveToTrash(path) {
     () => false
   )
 }
-
-// ── Release ─────────────────────────────────────────────────────────────────
-async function fetchWithRetry(url, attempts = 3) {
-  let failure
-  for (let attempt = 1; attempt <= attempts; attempt++) {
-    try {
-      const response = await fetch(url, { headers: { 'user-agent': `${PACKAGE} installer` }, redirect: 'follow' })
-      if (response.status === 404) return response
-      if (!response.ok) throw Error(`HTTP ${response.status}`)
-      return response
-    } catch (error) {
-      failure = error
-      await new Promise((resolve) => setTimeout(resolve, 600 * attempt))
-    }
-  }
-  throw Error(`Could not reach GitHub (${failure?.message ?? 'network error'}). Check your connection and run the command again.`)
-}
-async function readManifest(from) {
-  if (from) return parseInstallManifest(JSON.parse(await readFile(join(from, INSTALL_MANIFEST_FILE), 'utf8')))
-  const response = await fetchWithRetry(latestManifestUrl())
-  if (response.status === 404) throw Error('No Morphite release is available yet. Try again soon.')
-  return parseInstallManifest(await response.json())
-}
-async function download(manifest, archive, folder, from, progress) {
-  const destination = join(folder, archive.file)
-  const hash = createHash('sha256')
-  let received = 0
-  const report = () => progress(received / archive.size, `${megabytes(received)} of ${megabytes(archive.size)} MB`)
-  const output = createWriteStream(destination, { mode: 0o600 })
-  const write = async (chunk) => {
-    hash.update(chunk)
-    received += chunk.length
-    if (received > archive.size) throw Error('The download is larger than the release says. Nothing was installed.')
-    if (!output.write(chunk)) await once(output, 'drain')
-  }
-  const timer = setInterval(report, 120)
-  try {
-    if (from) {
-      const { createReadStream } = await import('node:fs')
-      for await (const chunk of createReadStream(join(from, archive.file))) await write(chunk)
-    } else {
-      const response = await fetchWithRetry(releaseFileUrl(manifest.tag, archive.file))
-      if (!response.ok || !response.body) throw Error(`The release file is unavailable (HTTP ${response.status}).`)
-      for await (const chunk of response.body) await write(chunk)
-    }
-    output.end()
-    await once(output, 'finish')
-  } finally {
-    clearInterval(timer)
-    output.destroy()
-  }
-  return { path: destination, sha256: hash.digest('hex'), size: received }
-}
-
-// ── Install ─────────────────────────────────────────────────────────────────
 async function writable(folder) {
   return access(folder, constants.W_OK).then(
     () => true,
     () => false
   )
 }
+const applications = '/Applications'
+const personal = join(homedir(), 'Applications')
+// Local release tests use a throwaway Applications folder. The installed app's identity and
+// destination cannot be redirected by a published installer or a production release.
+const testApplications = (manifest) =>
+  process.env.NODE_ENV === 'test' && option('--from') && manifest.bundleId === 'com.morphite.local'
+    ? process.env.MORPHITE_TEST_APPLICATIONS
+    : undefined
+/** INSTALLER_STEPS on macOS: the app bundle in Applications (or ~/Applications), opened with open. */
+const macSteps = {
+  computerName: 'Mac',
+  async computer() {
+    const macOS = (await run('/usr/bin/sw_vers', ['-productVersion'])).stdout.trim()
+    const cpu = await macCpu()
+    const chip = cpu === 'arm64' ? 'Apple silicon' : 'Intel'
+    return { cpu, chip, line: `macOS ${macOS} · ${chip}`, macOS }
+  },
+  unsupported: (manifest, computer) =>
+    versionAtLeast(computer.macOS, manifest.minimumMacOS)
+      ? null
+      : [`${manifest.name} needs macOS ${manifest.minimumMacOS} or later.`, `This Mac has macOS ${computer.macOS}.`],
+  async installed(manifest) {
+    const folders = testApplications(manifest) ? [testApplications(manifest)] : [applications, personal]
+    const installed = await appsWithId(folders, manifest.bundleId)
+    const current = installed.length ? await versionOf(installed[0]) : null
+    return { installed, current, earlier: testApplications(manifest) ? [] : await appsWithId(folders, EARLIER_APP_ID) }
+  },
+  placeOf: (app) => (dirname(app) === '/Applications' ? 'Applications' : tilde(dirname(app))),
+  async target(manifest) {
+    const target = testApplications(manifest) || ((await writable(applications)) ? applications : personal)
+    return { target, place: target === applications ? 'Applications' : tilde(target), destination: join(target, `${manifest.name}.app`) }
+  },
+  async unpack(zip, stage, manifest) {
+    await unpackApp(zip, stage)
+    return join(stage, `${manifest.name}.app`)
+  },
+  verify: (candidate, manifest) => verifyApp(candidate, { bundleId: manifest.bundleId, version: manifest.version }),
+  prepare: (candidate) => clearQuarantine(candidate),
+  running: (apps, manifest) => testApplications(manifest)
+    ? Promise.resolve([])
+    : runningFrom(apps),
+  nameOf: (app) => basename(app, '.app'),
+  // No keyboard shortcut is suggested: ⌘Q here would quit Terminal.
+  quitHint: (names, work) => `Quit it from its menu bar (${names} → Quit), and this ${work} continues on its own.`,
+  quit: (id) => void run('/usr/bin/osascript', ['-e', `tell application id ${JSON.stringify(id)} to quit`]).catch(() => undefined),
+  aside: (stage, index) => join(stage, `previous-${index}.app`),
+  afterInstall: async () => undefined,
+  open: (app) => run('/usr/bin/open', [app]).then(() => true, () => false),
+  ready: (opened, place) => (opened ? `It’s open now, and in ${place} and Spotlight.` : `Open it from ${place} or Spotlight.`)
+}
+
+// ── Windows ─────────────────────────────────────────────────────────────────
+/** INSTALLER_STEPS on Windows (WINDOWS_INSTALL): %LOCALAPPDATA%\Programs\<name> and a Start-menu
+ *  shortcut; no administrator, nothing else registered. */
+const windowsSteps = {
+  computerName: 'PC',
+  async computer() {
+    const cpu = nodeArch()
+    return { cpu, chip: `Windows ${cpu}`, line: `Windows ${windowsVersion()} · ${cpu}` }
+  },
+  unsupported: () =>
+    supportedWindows() ? null : ['Morphite needs Windows 10 (version 1803) or later.', `This PC has Windows ${windowsVersion()}.`],
+  async installed(manifest) {
+    const folder = join(windowsPlaces().programs, manifest.name)
+    const info = await windowsAppInfo(folder, manifest.name)
+    return { installed: info?.name === manifest.name ? [folder] : [], current: info?.name === manifest.name ? info.version : null, earlier: [] }
+  },
+  placeOf: (app) => tilde(dirname(app)),
+  async target(manifest) {
+    const target = windowsPlaces().programs
+    return { target, place: tilde(target), destination: join(target, manifest.name) }
+  },
+  unpack: (zip, stage) => unpackWindowsApp(zip, stage),
+  verify: (candidate, manifest) => verifyWindowsApp(candidate, manifest, AppCheckError),
+  prepare: async () => undefined,
+  running: runningWindowsApps,
+  nameOf: (app) => basename(app),
+  // Closing Morphite's window keeps it in the tray, so its tray icon is where it quits.
+  quitHint: (names, work) => `Quit it from its tray icon (${names} → Quit Morphite), and this ${work} continues on its own.`,
+  quit: null,
+  aside: (stage, index) => join(stage, `previous-${index}`),
+  async afterInstall(destination, manifest) {
+    await writeStartMenuShortcut(windowsPlaces(), destination, manifest).then(
+      () => say(grey('Added to the Start menu')),
+      (error) => say(grey(`Couldn’t add ${manifest.name} to the Start menu (${String(error?.message ?? error).split('\n')[0]})`))
+    )
+  },
+  open: (app, manifest) => openWindowsApp(app, manifest.name),
+  ready: (opened) => (opened ? 'It’s open now, and in the Start menu.' : 'Open it from the Start menu.')
+}
+
+// ── Install ─────────────────────────────────────────────────────────────────
 async function main() {
+  const host = platform() === 'darwin' ? macSteps : platform() === 'win32' ? windowsSteps : null
   if (flag('--help') || flag('-h')) {
-    say('', bold('npx ' + PACKAGE), grey('Installs or updates Morphite on this Mac.'), '',
+    say('', bold('npx ' + PACKAGE), grey(`Installs or updates Morphite on this ${host?.computerName ?? 'computer'}.`), '',
       `--yes        ${grey('Answer yes to every question')}`,
       `--no-open    ${grey('Do not open Morphite afterwards')}`,
       `--reinstall  ${grey('Install again even when this version is installed')}`,
@@ -205,18 +255,16 @@ async function main() {
     return
   }
   const from = option('--from')
-  if (platform() !== 'darwin') {
+  if (!host) {
     header('Morphite')
-    note('Morphite runs on macOS for now.', 'Windows and Linux are on the way. Follow along at https://morphite.build')
+    note('Morphite runs on macOS and Windows for now.', 'Linux is on the way. Follow along at https://morphite.build')
     say('')
     process.exitCode = 1
     return
   }
 
   live.set(grey('Checking for the latest release…'))
-  const macOS = (await run('/usr/bin/sw_vers', ['-productVersion'])).stdout.trim()
-  const cpu = await macCpu()
-  const chip = cpu === 'arm64' ? 'Apple silicon' : 'Intel'
+  const computer = await host.computer()
   // The header names the app and version from the release, so read it before printing anything else.
   let manifest
   try {
@@ -231,30 +279,27 @@ async function main() {
   }
   live.clear()
   header(manifest.name, manifest.version)
-  say(grey(`macOS ${macOS} · ${chip}`))
-  if (!versionAtLeast(macOS, manifest.minimumMacOS)) {
-    note(`${manifest.name} needs macOS ${manifest.minimumMacOS} or later.`, `This Mac has macOS ${macOS}.`)
+  say(grey(computer.line))
+  const unsupported = host.unsupported(manifest, computer)
+  if (unsupported) {
+    note(...unsupported)
     say('')
     process.exitCode = 1
     return
   }
-  const archive = manifest.archives[cpu]
+  const archive = manifest.archives[archiveTarget(platform(), computer.cpu)]
   if (!archive) {
-    note(`This release has no ${chip} build yet.`, 'Nothing was changed.')
+    note(`This release has no ${computer.chip} build yet.`, 'Nothing was changed.')
     say('')
     process.exitCode = 1
     return
   }
-  const applications = '/Applications'
-  const personal = join(homedir(), 'Applications')
-  const installed = await appsWithId([applications, personal], manifest.bundleId)
-  const current = installed.length ? await versionOf(installed[0]) : null
-  const earlier = await appsWithId([applications, personal], EARLIER_APP_ID)
+  const { installed, current, earlier } = await host.installed(manifest)
 
   // Already current (and nothing earlier to retire): say so and open it, without downloading again.
   if (current === manifest.version && !earlier.length && !flag('--reinstall')) {
-    const opened = !flag('--no-open') && (await run('/usr/bin/open', [installed[0]]).then(() => true, () => false))
-    note('You’re up to date.', `${manifest.name} ${manifest.version} is installed in ${dirname(installed[0]) === '/Applications' ? 'Applications' : tilde(dirname(installed[0]))}.${opened ? ' It’s open now.' : ''}`)
+    const opened = !flag('--no-open') && (await host.open(installed[0], manifest))
+    note('You’re up to date.', `${manifest.name} ${manifest.version} is installed in ${host.placeOf(installed[0])}.${opened ? ' It’s open now.' : ''}`)
     say('')
     return
   }
@@ -277,9 +322,7 @@ async function main() {
     say('')
   }
 
-  const target = (await writable(applications)) ? applications : personal
-  const place = target === applications ? 'Applications' : tilde(target)
-  const destination = join(target, `${manifest.name}.app`)
+  const { target, place, destination } = await host.target(manifest)
   const work = await mkdtemp(join(tmpdir(), 'morphite-installer-'))
   const cleanup = () => rm(work, { recursive: true, force: true }).catch(() => undefined)
   const stopped = () => {
@@ -298,11 +341,15 @@ async function main() {
   try {
     let file
     try {
-      file = await download(manifest, archive, work, from, (ratio, detail) => live.set(progressLine(ratio, detail)))
+      file = await downloadArchive(manifest, archive, join(work, archive.file), {
+        from,
+        userAgent: `${PACKAGE} installer`,
+        progress: (ratio, received) => live.set(progressLine(ratio, `${megabytes(received)} of ${megabytes(archive.size)} MB`))
+      })
     } catch (error) {
       throw stop('The download stopped.', `${error.message} Nothing was changed.`)
     }
-    if (file.size !== archive.size || file.sha256 !== archive.sha256)
+    if (!archiveMatches(file, archive))
       throw stop('The download doesn’t match the release.', 'Nothing was changed. Run the command again.')
     live.done(progressLine(1, `${megabytes(file.size)} MB · verified`))
 
@@ -311,38 +358,32 @@ async function main() {
     // Stage beside the destination so the final move is a rename on the same disk.
     const stage = await mkdtemp(join(target, '.morphite-install-'))
     try {
-      await run('/usr/bin/ditto', ['-x', '-k', file.path, stage])
-      const candidate = join(stage, `${manifest.name}.app`)
-      if ((await bundleIdOf(candidate)) !== manifest.bundleId) throw stop('The downloaded app isn’t the expected Morphite build.', 'Nothing was changed.')
-      await run('/usr/bin/codesign', ['--verify', '--deep', '--strict', candidate]).catch(() => {
-        throw stop('The downloaded app failed its signature check.', 'Nothing was changed.')
+      const candidate = await host.unpack(file.path, stage, manifest)
+      await host.verify(candidate, manifest).catch((error) => {
+        throw stop(error.message, 'Nothing was changed.')
       })
-      // Fetched by this program, the app carries no download mark; clear one defensively all the same.
-      await run('/usr/bin/xattr', ['-dr', 'com.apple.quarantine', candidate]).catch(() => undefined)
+      await host.prepare(candidate)
 
-      // Morphite must be closed before its app is replaced. The person quits it from its menu, or
-      // presses Enter and the installer asks it to quit the normal way (never a forced stop, so its
-      // work ends cleanly). No keyboard shortcut is suggested: ⌘Q here would quit Terminal.
-      let open = await runningFrom([...installed, ...earlier])
+      // Morphite must be closed before its app is replaced. The person quits it themselves, or on a
+      // Mac presses Enter and the installer asks it to quit the normal way (never a forced stop, so
+      // its work ends cleanly).
+      let open = await host.running([...installed, ...earlier], manifest)
       if (open.length) {
-        const names = open.map((app) => basename(app, '.app')).join(' and ')
+        const names = open.map((app) => host.nameOf(app)).join(' and ')
         live.clear()
         note(
           `${names} is open.`,
-          `Quit it from its menu bar (${names} → Quit), and this ${current ? 'update' : 'install'} continues on its own.`,
-          tty ? 'Or press Return to quit it now. Control-C stops without changing anything.' : 'Control-C stops without changing anything.'
+          host.quitHint(names, current ? 'update' : 'install'),
+          tty && host.quit ? 'Or press Return to quit it now. Control-C stops without changing anything.' : 'Control-C stops without changing anything.'
         )
         say('')
         const input = tty && process.stdin.isTTY ? process.stdin : null
         const key = (data) => {
           const text = String(data)
           if (text.includes('\u0003')) return stopped()
-          if (!/[\r\n]/.test(text)) return
+          if (!/[\r\n]/.test(text) || !host.quit) return
           live.set(grey(`Quitting ${names}…`))
-          for (const app of open) {
-            const id = earlier.includes(app) ? EARLIER_APP_ID : manifest.bundleId
-            void run('/usr/bin/osascript', ['-e', `tell application id ${JSON.stringify(id)} to quit`]).catch(() => undefined)
-          }
+          for (const app of open) host.quit(earlier.includes(app) ? EARLIER_APP_ID : manifest.bundleId)
         }
         if (input) {
           input.setRawMode(true)
@@ -353,7 +394,7 @@ async function main() {
         try {
           while (open.length) {
             await new Promise((resolve) => setTimeout(resolve, 700))
-            open = await runningFrom([...installed, ...earlier])
+            open = await host.running([...installed, ...earlier], manifest)
           }
         } finally {
           if (input) {
@@ -366,23 +407,13 @@ async function main() {
         live.set(grey(`${current ? 'Updating' : 'Installing'} in ${place}…`))
       }
 
-      const replaced = []
       try {
         // Set the old app aside in the staging folder; it is removed with that folder only once the
-        // new app is in place, as any Mac updater does. The bundle holds no data: projects, settings
-        // and sign-in live outside it.
-        for (const previous of installed) {
-          const aside = join(stage, `previous-${replaced.length}.app`)
-          await rename(previous, aside)
-          replaced.push([previous, aside])
-        }
-        if (await stat(destination).catch(() => null)) throw Error(`${tilde(destination)} already exists and isn’t ${manifest.name}.`)
-        await rename(candidate, destination)
+        // new app is in place, as any updater does. On failure every earlier copy is put back
+        // (APP_SWAP). The app holds no data: projects, settings and sign-in live outside it.
+        await swapApps(installed, candidate, destination, (index) => host.aside(stage, index))
       } catch (error) {
-        // Put every earlier copy back where it was; the install did not happen.
-        for (const [original, moved] of replaced.reverse()) await rename(moved, original).catch(() => undefined)
-        if (error.reported) throw error
-        throw stop(`${manifest.name} couldn’t be installed.`, `${error.message} Nothing was changed.`)
+        throw stop(`${manifest.name} couldn’t be installed.`, `${error.message.replace(destination, tilde(destination))} Nothing was changed.`)
       }
       live.done(grey(`${current ? 'Updated' : 'Installed'} in ${place}`))
     } finally {
@@ -392,13 +423,10 @@ async function main() {
     // Agreed above: the earlier app goes to the Trash (recoverable); its data folder stays.
     for (const app of earlier)
       say(grey((await moveToTrash(app)) ? 'Moved the earlier Morphite to the Trash' : `Drag ${basename(app)} from ${tilde(dirname(app))} to the Trash`))
+    await host.afterInstall(destination, manifest)
 
-    const opened = !flag('--no-open') && (await run('/usr/bin/open', [destination]).then(() => true, () => false))
-    note(
-      `${manifest.name} is ready.`,
-      opened ? `It’s open now, and in ${place} and Spotlight.` : `Open it from ${place} or Spotlight.`,
-      'Run this command again to update.'
-    )
+    const opened = !flag('--no-open') && (await host.open(destination, manifest))
+    note(`${manifest.name} is ready.`, host.ready(opened, place), 'Run this command again to update.')
     say('')
   } finally {
     await cleanup()

package/manifest.mjs

@@ -1,16 +1,28 @@
 /** SOURCE OF TRUTH KEYWORDS: installManifest, INSTALL_MANIFEST, parseInstallManifest, INSTALL_MANIFEST_FILE
  * WHAT: The one file a Morphite release carries for the terminal installer: the app's name, bundle
- *   id and version, and for each Mac CPU the zipped app with its size and SHA-256.
+ *   id and version, and for each Mac CPU (and Windows, as windows-x64) the zipped app with its size
+ *   and SHA-256.
  * WHY: The installer trusts nothing it has not checked: it installs only releases that carry this
  *   file (earlier releases without it are never picked up), checks every field before a path or URL
  *   is built from it, and refuses an archive whose size or hash differs.
- * WHERE: scripts/release-publish.ts writes it beside the zips; bin/morphite.mjs reads it from the
- *   releases repository (or a local folder with --from). Plain JavaScript so the published installer
- *   has no dependencies.
+ * WHERE: writeReleaseFiles writes it beside the zips (scripts/release-publish.ts, and the local
+ *   update test kit scripts/update-try.ts); bin/morphite.mjs and the app's own Update
+ *   (app-update.mjs readManifest → src/desktop/updates/release-install.ts) read it from the releases
+ *   repository or a local folder. Plain JavaScript so the published installer has no dependencies.
  */
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
 export const INSTALL_MANIFEST_FILE = 'morphite-install.json'
 export const RELEASES_REPOSITORY = 'webprodigies-org/morphite-releases'
 export const MAC_ARCHES = ['arm64', 'x64']
+/** Every archive a release can carry: Mac CPUs by their bare names (as earlier releases have them),
+ *  Windows as windows-<cpu>. Installers that predate Windows read only the Mac keys. */
+export const ARCHIVE_TARGETS = [...MAC_ARCHES, 'windows-x64']
+/** The archive key for this computer. */
+export const archiveTarget = (system, cpu) => (system === 'win32' ? `windows-${cpu}` : cpu)
 
 const text = (value, pattern, field) => {
   if (typeof value !== 'string' || !pattern.test(value)) throw Error(`Release manifest: invalid ${field}.`)
@@ -21,7 +33,7 @@ const text = (value, pattern, field) => {
 export function parseInstallManifest(input) {
   if (!input || typeof input !== 'object' || input.format !== 1) throw Error('Release manifest: unsupported format.')
   const archives = {}
-  for (const arch of MAC_ARCHES) {
+  for (const arch of ARCHIVE_TARGETS) {
     const entry = input.archives?.[arch]
     if (!entry) continue
     archives[arch] = {
@@ -30,7 +42,7 @@ export function parseInstallManifest(input) {
       size: Number.isSafeInteger(entry.size) && entry.size > 0 ? entry.size : text('', /x/, `${arch} size`)
     }
   }
-  if (!Object.keys(archives).length) throw Error('Release manifest: no Mac archives.')
+  if (!Object.keys(archives).length) throw Error('Release manifest: no archives.')
   return {
     format: 1,
     // The app's folder name in Applications, e.g. "Morphite (Alpha)".
@@ -47,3 +59,24 @@ export const releaseFileUrl = (tag, file) =>
   `https://github.com/${RELEASES_REPOSITORY}/releases/download/${encodeURIComponent(tag)}/${encodeURIComponent(file)}`
 export const latestManifestUrl = () =>
   `https://github.com/${RELEASES_REPOSITORY}/releases/latest/download/${INSTALL_MANIFEST_FILE}`
+
+/** Describes the zips already in `folder` for a release: measures each, writes morphite-install.json
+ *  and SHA256SUMS beside them and returns the checked manifest. Used by release:publish and the
+ *  local update test kit (update:try), so a local release has the published format. */
+export async function writeReleaseFiles(folder, { files, ...release }) {
+  const archives = {}
+  for (const arch of ARCHIVE_TARGETS) {
+    const file = files[arch]
+    if (!file) continue
+    const hash = createHash('sha256')
+    for await (const chunk of createReadStream(join(folder, file))) hash.update(chunk)
+    archives[arch] = { file, sha256: hash.digest('hex'), size: (await stat(join(folder, file))).size }
+  }
+  const manifest = parseInstallManifest({ format: 1, ...release, archives })
+  await writeFile(join(folder, INSTALL_MANIFEST_FILE), JSON.stringify(manifest, null, 2) + '\n')
+  await writeFile(
+    join(folder, 'SHA256SUMS'),
+    Object.values(manifest.archives).map((entry) => `${entry.sha256}  ${entry.file}`).join('\n') + '\n'
+  )
+  return manifest
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webprodigies/morphite",
-  "version": "0.2.2",
-  "description": "Install or update Morphite on your Mac: npx @webprodigies/morphite",
+  "version": "0.2.4",
+  "description": "Install or update Morphite on your Mac or Windows PC: npx @webprodigies/morphite",
   "type": "module",
   "bin": {
     "morphite": "bin/morphite.mjs"
@@ -9,6 +9,8 @@
   "files": [
     "bin/morphite.mjs",
     "manifest.mjs",
+    "windows.mjs",
+    "app-update.mjs",
     "README.md"
   ],
   "engines": {

package/windows.mjs

@@ -0,0 +1,154 @@
+/** SOURCE OF TRUTH KEYWORDS: windowsInstallSteps, WINDOWS_INSTALL, writeStartMenuShortcut
+ * WHAT: The Windows steps of the terminal installer. The app lives in %LOCALAPPDATA%\Programs\<name>
+ *   for this person only (no administrator), is unpacked with Windows' own tar, checked by its exe's
+ *   product name and version, and gets one Start-menu shortcut whose AppUserModelID is the release's
+ *   bundle id: Windows groups the app's windows and notifications by that id, and Electron's
+ *   app.setAppUserModelId (desktop main) sets the same. Nothing else is registered.
+ * WHY: One terminal installer for every OS (bin/morphite.mjs); only these steps differ on Windows.
+ *   The shortcut is written here, not by the app, so Morphite is in the Start menu before it first runs.
+ * WHERE: bin/morphite.mjs runs these beside its Mac steps; ../app-update.mjs's download, archive check
+ *   and swap are shared. User data (appDataFolder: %LOCALAPPDATA%\<profile>) is outside Programs and
+ *   is never touched here. Plain JavaScript: the installer has no build step or dependencies.
+ */
+import { spawn, execFile } from 'node:child_process'
+import { mkdir, readdir, stat } from 'node:fs/promises'
+import { homedir, release } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+const run = promisify(execFile)
+const variable = (env, name) => env[Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase()) ?? name]
+const system32 = (env = process.env) => join(variable(env, 'SystemRoot') || variable(env, 'windir') || 'C:\\Windows', 'System32')
+const powershell = (env = process.env) => join(system32(env), 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+/** PowerShell with the script as -EncodedCommand (no quoting on the way) and its inputs as variables.
+ *  A failure carries PowerShell's own first error line, not the encoded command. */
+function runPowerShell(script, values = {}) {
+  const encoded = Buffer.from(script, 'utf16le').toString('base64')
+  return run(powershell(), ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded], {
+    env: { ...process.env, ...values },
+    windowsHide: true,
+    maxBuffer: 16 * 1024 * 1024
+  }).catch((error) => {
+    const reason = String(error.stderr ?? '').split(/\r?\n/).map((line) => line.trim()).find(Boolean)
+    throw Error(reason || 'PowerShell could not finish.')
+  })
+}
+
+/** Where the app and its shortcut go for this person. */
+export function windowsPlaces(env = process.env, home = homedir()) {
+  const local = variable(env, 'LOCALAPPDATA') || join(home, 'AppData', 'Local')
+  const roaming = variable(env, 'APPDATA') || join(home, 'AppData', 'Roaming')
+  return {
+    programs: join(local, 'Programs'),
+    startMenu: join(roaming, 'Microsoft', 'Windows', 'Start Menu', 'Programs')
+  }
+}
+/** "Windows 10" or later, by the kernel's 10.0 version; tar and curl ship with Windows 10 1803 on. */
+export const windowsVersion = () => release()
+export const supportedWindows = (version = release()) => Number(version.split('.')[0]) >= 10 && Number(version.split('.')[2] ?? 0) >= 17134
+export const exeOf = (folder, name) => join(folder, `${name}.exe`)
+
+/** The installed copy's product name and version from its exe, or null. */
+export async function windowsAppInfo(folder, name) {
+  const exe = exeOf(folder, name)
+  if (!(await stat(exe).catch(() => null))?.isFile()) return null
+  const { stdout } = await runPowerShell(
+    '$v = (Get-Item -LiteralPath $env:MORPHITE_EXE).VersionInfo; @{ name = $v.ProductName; version = $v.ProductVersion; file = $v.FileVersion } | ConvertTo-Json -Compress',
+    { MORPHITE_EXE: exe }
+  ).catch(() => ({ stdout: '' }))
+  try {
+    const info = JSON.parse(stdout)
+    return { name: info.name ?? null, version: info.version ?? info.file ?? null }
+  } catch {
+    return null
+  }
+}
+
+/** Unpacks a release zip into `folder` and returns the app folder it holds (the zip's one folder). */
+export async function unpackWindowsApp(zip, folder) {
+  await run(join(system32(), 'tar.exe'), ['-x', '-f', zip, '-C', folder], { windowsHide: true })
+  const entries = (await readdir(folder, { withFileTypes: true })).filter((entry) => entry.isDirectory())
+  if (entries.length !== 1) throw Error('The release zip doesn’t hold one app folder.')
+  return join(folder, entries[0].name)
+}
+
+/** Throws unless `app` is the named Morphite build at the release's version, with its app archive. */
+export async function verifyWindowsApp(app, { name, version }, CheckError = Error) {
+  const info = await windowsAppInfo(app, name)
+  if (!info || info.name !== name) throw new CheckError('bundle-id', 'The downloaded app isn’t the expected Morphite build.')
+  if (info.version !== version) throw new CheckError('version', 'The downloaded app isn’t the version the release names.')
+  // Listed, never opened: inside Morphite, Electron's fs treats app.asar as an archive (and keeps it
+  // open, so the staging folder could not be removed).
+  const resources = await readdir(join(app, 'resources')).catch(() => [])
+  if (!resources.includes('app.asar')) throw new CheckError('bundle-id', 'The downloaded app isn’t the expected Morphite build.')
+}
+
+/** The app folders among `folders` with a program running from inside them. */
+export async function runningWindowsApps(folders) {
+  if (!folders.length) return []
+  const { stdout } = await runPowerShell(
+    '(Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath } | ForEach-Object { $_.ExecutablePath }) -join "`n"'
+  ).catch(() => ({ stdout: '' }))
+  const paths = stdout.split(/\r?\n/).map((path) => path.trim().toLowerCase()).filter(Boolean)
+  return folders.filter((folder) => paths.some((path) => path.startsWith(folder.toLowerCase() + '\\')))
+}
+
+// A Start-menu shortcut with an AppUserModelID needs the shell's own link object and property store.
+const SHORTCUT = String.raw`
+Add-Type -TypeDefinition @'
+using System; using System.Runtime.InteropServices; using System.Runtime.InteropServices.ComTypes; using System.Text;
+[ComImport, Guid("00021401-0000-0000-C000-000000000046")] class CShellLink {}
+[ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("000214F9-0000-0000-C000-000000000046")]
+interface IShellLinkW {
+  void GetPath([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder f, int c, IntPtr d, uint fl); void GetIDList(out IntPtr p); void SetIDList(IntPtr p);
+  void GetDescription([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder n, int c); void SetDescription([MarshalAs(UnmanagedType.LPWStr)] string n);
+  void GetWorkingDirectory([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder d, int c); void SetWorkingDirectory([MarshalAs(UnmanagedType.LPWStr)] string d);
+  void GetArguments([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder a, int c); void SetArguments([MarshalAs(UnmanagedType.LPWStr)] string a);
+  void GetHotkey(out short h); void SetHotkey(short h); void GetShowCmd(out int s); void SetShowCmd(int s);
+  void GetIconLocation([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder p, int c, out int i); void SetIconLocation([MarshalAs(UnmanagedType.LPWStr)] string p, int i);
+  void SetRelativePath([MarshalAs(UnmanagedType.LPWStr)] string p, uint r); void Resolve(IntPtr h, uint f); void SetPath([MarshalAs(UnmanagedType.LPWStr)] string f);
+}
+[ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("886D8EEB-8CF2-4446-8D02-CDBA1DBDCF99")]
+interface IPropertyStore { void GetCount(out uint c); void GetAt(uint i, out PropertyKey k); void GetValue(ref PropertyKey k, out PropVariant v); void SetValue(ref PropertyKey k, ref PropVariant v); void Commit(); }
+[StructLayout(LayoutKind.Sequential, Pack = 4)] public struct PropertyKey { public Guid fmtid; public uint pid; }
+[StructLayout(LayoutKind.Explicit)] public struct PropVariant { [FieldOffset(0)] public ushort vt; [FieldOffset(8)] public IntPtr value; }
+public static class MorphiteShortcut {
+  public static void Write(string link, string target, string folder, string id) {
+    var shell = (IShellLinkW)new CShellLink();
+    shell.SetPath(target); shell.SetWorkingDirectory(folder); shell.SetIconLocation(target, 0);
+    var key = new PropertyKey { fmtid = new Guid("9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3"), pid = 5 };
+    var value = new PropVariant { vt = 31, value = Marshal.StringToCoTaskMemUni(id) };
+    try { var store = (IPropertyStore)shell; store.SetValue(ref key, ref value); store.Commit(); ((IPersistFile)shell).Save(link, true); }
+    finally { Marshal.FreeCoTaskMem(value.value); }
+  }
+}
+'@
+[MorphiteShortcut]::Write($env:MORPHITE_LINK, $env:MORPHITE_TARGET, $env:MORPHITE_FOLDER, $env:MORPHITE_APP_ID)
+`
+/** Writes (or replaces) the Start-menu shortcut to the app, with its AppUserModelID. */
+export async function writeStartMenuShortcut({ startMenu }, app, { name, bundleId }) {
+  const link = join(startMenu, `${name}.lnk`)
+  await mkdir(startMenu, { recursive: true })
+  await runPowerShell(SHORTCUT, { MORPHITE_LINK: link, MORPHITE_TARGET: exeOf(app, name), MORPHITE_FOLDER: app, MORPHITE_APP_ID: bundleId })
+  return link
+}
+/** The AppUserModelID a shortcut carries, as the shell reads it. */
+export async function shortcutAppId(link) {
+  const { stdout } = await runPowerShell(
+    '$f = Get-Item -LiteralPath $env:MORPHITE_LINK; (New-Object -ComObject Shell.Application).NameSpace($f.DirectoryName).ParseName($f.Name).ExtendedProperty("System.AppUserModel.ID")',
+    { MORPHITE_LINK: link }
+  )
+  return stdout.trim() || null
+}
+
+/** Starts the app on its own, as the Start menu would. */
+export async function openWindowsApp(app, name) {
+  return new Promise((resolve) => {
+    const child = spawn(exeOf(app, name), [], { cwd: app, detached: true, stdio: 'ignore', windowsHide: false })
+    child.once('error', () => resolve(false))
+    child.once('spawn', () => {
+      child.unref()
+      resolve(true)
+    })
+  })
+}