@webprodigies/morphite 0.2.3 → 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

@@ -9,7 +9,8 @@
  *   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; manifest.mjs owns the release format. Plain JavaScript: the installer has no
+ *   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'
@@ -180,3 +181,101 @@ if [ "$result" -eq 0 ]; then say "Updated $destination."; opened=$destination; e
 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,15 +1,17 @@
 #!/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 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 bundle and is never touched here.
+ *   User data lives outside the app and is never touched here.
  */
 import { access, constants, lstat, mkdir, mkdtemp, readdir, rm } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
@@ -17,7 +19,19 @@ import { homedir, platform, tmpdir, arch as nodeArch } from 'node:os'
 import { join, basename, dirname } from 'node:path'
 import { createInterface } from 'node:readline'
 import { promisify } from 'node:util'
-import { archiveMatches, clearQuarantine, downloadArchive, readManifest, swapApps, unpackApp, verifyApp } from '../app-update.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)
@@ -132,17 +146,108 @@ async function moveToTrash(path) {
     () => false
   )
 }
-
-// ── 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')}`,
@@ -150,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 {
@@ -176,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
   }
@@ -222,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 = () => {
@@ -260,36 +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 unpackApp(file.path, stage)
-      const candidate = join(stage, `${manifest.name}.app`)
-      await verifyApp(candidate, { bundleId: manifest.bundleId, version: manifest.version }).catch((error) => {
+      const candidate = await host.unpack(file.path, stage, manifest)
+      await host.verify(candidate, manifest).catch((error) => {
         throw stop(error.message, 'Nothing was changed.')
       })
-      await clearQuarantine(candidate)
+      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)
@@ -300,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) {
@@ -315,9 +409,9 @@ async function main() {
 
       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. On failure every earlier copy is put back
-        // (APP_SWAP). The bundle holds no data: projects, settings and sign-in live outside it.
-        await swapApps(installed, candidate, destination, (index) => join(stage, `previous-${index}.app`))
+        // 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) {
         throw stop(`${manifest.name} couldn’t be installed.`, `${error.message.replace(destination, tilde(destination))} Nothing was changed.`)
       }
@@ -329,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,6 +1,7 @@
 /** 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.
@@ -17,6 +18,11 @@ 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}.`)
@@ -27,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] = {
@@ -36,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)".
@@ -59,7 +65,7 @@ export const latestManifestUrl = () =>
  *  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 MAC_ARCHES) {
+  for (const arch of ARCHIVE_TARGETS) {
     const file = files[arch]
     if (!file) continue
     const hash = createHash('sha256')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webprodigies/morphite",
-  "version": "0.2.3",
-  "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,7 @@
   "files": [
     "bin/morphite.mjs",
     "manifest.mjs",
+    "windows.mjs",
     "app-update.mjs",
     "README.md"
   ],

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)
+    })
+  })
+}