centralu 0.1.0-beta.4 → 0.1.0-beta.41

package/bin/node-floor.mjs

@@ -0,0 +1,42 @@
+/**
+ * The oldest Node the bundled host runs on, and what the launcher says when it is run on an older one.
+ *
+ * **The floor is `engines.node` of this package, read here and nowhere restated.** The host's native
+ * database module (better-sqlite3 13) declares Node-API 10, which Node has from 22.14.0. Under an
+ * older 22.x (and under 20) it loads, then crashes on its first use with an access violation
+ * (`0xC0000005`, exit 3221225477, on Windows) or SIGSEGV (measured on 22.12.0, Windows and macOS,
+ * issue #699), before the host logs a line. The hub reads the same value from its copy of this
+ * package's `package.json` (`packages/agent-host/src/links/node-floor.ts`), and
+ * `tooling/engines.test.ts` keeps the other declarations equal to it.
+ *
+ * Lives in its own file so it can be tested (tooling/launcher-node-floor.test.ts): the launcher
+ * itself runs commands at import time. Plain JavaScript on Node's own modules and `semver.mjs`.
+ */
+import { isNewer } from './semver.mjs'
+
+/** `>=22.14.0` or `>=22.14` → `22.14.0`; throws on any other shape, which `engines` must not take */
+export function floorOf(range) {
+  const m = /^>=\s*(\d+)\.(\d+)(?:\.(\d+))?$/.exec(String(range).trim())
+  if (!m) throw new Error(`engines.node must be a plain floor like ">=22.14.0", not ${JSON.stringify(range)}`)
+  return `${m[1]}.${m[2]}.${m[3] ?? '0'}`
+}
+
+/** Whether `found` (`22.12.0` or `v22.12.0`) is older than `floor`; a version that does not parse is let through */
+export function belowFloor(found, floor) {
+  const v = String(found).trim().replace(/^v/i, '')
+  if (!/^\d+\.\d+\.\d+/.test(v)) return false
+  return isNewer(floor, v)
+}
+
+/**
+ * The one sentence for a launcher that will not start the host on this Node: the Node it found, the
+ * floor, and the two ways out. It names no command, since it is also what the hub reads out of the
+ * `--detach` answer.
+ */
+export function oldNodeSentence(found, floor) {
+  const v = String(found).replace(/^v/i, '')
+  return (
+    `centralu serve needs Node ${floor} or newer and this is Node ${v}: update Node on this machine, ` +
+    'or link this machine from a Centralu window on another computer, which installs a Node of its own there.'
+  )
+}

package/bin/platform.mjs

@@ -0,0 +1,380 @@
+/**
+ * The launcher's per-platform decisions, as plain functions of the platform.
+ *
+ * Lives apart from `centralu.mjs` for the same reason `semver.mjs` does: the launcher runs
+ * a command at import time, so a test cannot import it. Everything here takes the platform
+ * (and the environment, and the home folder) as an argument instead of reading `process`,
+ * so `tooling/launcher-platform.test.ts` can ask what Windows would do from a Mac — which
+ * is the only place this project can run a test before the Windows package ships.
+ *
+ * package.json "files" lists the whole bin/ directory, so this ships automatically.
+ */
+import { posix, win32 } from 'node:path'
+
+export const APP_NAME = 'Centralu'
+
+/**
+ * The arch package for each machine, and what the app is called inside it.
+ *
+ * `artifact` must match `scripts/release-npm.mts` exactly — that script renames what
+ * Tauri produced (`Centralu_0.1.0-beta.2_amd64.AppImage`) to a fixed name precisely so
+ * the launcher does not have to know version or architecture. If the two ever disagree
+ * the symptom is "installed fine, does nothing".
+ *
+ * Only combinations that are actually published belong here. Listing a package that was
+ * never released would turn "not supported yet" into "your install is broken", which
+ * sends the user off to reinstall something that can never appear.
+ * `tooling/launcher-platform.test.ts` holds this table to the shim's `optionalDependencies`.
+ *
+ * Windows ships a folder, not a single file: `Centralu\centralu.exe` beside
+ * `Centralu\resources\host\`. Tauri looks for its resources next to the exe when nothing
+ * is installed, so the folder runs where npm unpacked it (#14, W1 in #307).
+ */
+export const TARGETS = {
+  'darwin-arm64': { pkg: '@centralu/darwin-arm64', artifact: `${APP_NAME}.app` },
+  'linux-arm64': { pkg: '@centralu/linux-arm64', artifact: `${APP_NAME}.AppImage` },
+  'linux-x64': { pkg: '@centralu/linux-x64', artifact: `${APP_NAME}.AppImage` },
+  'win32-x64': { pkg: '@centralu/win32-x64', artifact: APP_NAME },
+}
+
+/** The target for a platform/arch pair, or null when nothing is published for it. */
+export function targetFor(platform, arch) {
+  return TARGETS[`${platform}-${arch}`] ?? null
+}
+
+/**
+ * Whether replacing a file by rename fails while another program has the target open (a reader, a virus scanner):
+ * Windows, which then answers EPERM, EBUSY or EACCES for a moment. Elsewhere a rename over an open file just works.
+ */
+export function renameWaitsForReaders(platform = process.platform) {
+  return platform === 'win32'
+}
+
+/**
+ * The file that proves the artifact is there and is what gets started.
+ *
+ * On macOS and Linux that is the artifact itself (a bundle handed to `open`, an AppImage
+ * run directly). On Windows the artifact is a folder, and a folder that exists without its
+ * exe — an interrupted extract — must count as missing, not as found.
+ */
+export function executableIn(platform, app) {
+  return platform === 'win32' ? win32.join(app, 'centralu.exe') : app
+}
+
+/**
+ * The bundled host (`resources/host`, the folder whose `main.mjs` the app runs) inside a
+ * platform package, for `centralu serve` (#82).
+ *
+ * - macOS: inside the bundle, where Tauri puts `bundle.resources`.
+ * - Windows: beside the exe, which is already how the folder ships (W1 in #307).
+ * - Linux: a `host/` folder next to the AppImage. The host inside the AppImage sits in a
+ *   squashfs that is only reachable by mounting it (FUSE, which headless servers often lack)
+ *   or by extracting it on every start, so `scripts/release-npm.mts` ships the same folder a
+ *   second time, unpacked. It is 11 MB; the AppImage is several times that.
+ */
+export function hostDirIn(platform, app) {
+  if (platform === 'darwin') return posix.join(app, 'Contents', 'Resources', 'resources', 'host')
+  if (platform === 'win32') return win32.join(app, 'resources', 'host')
+  return posix.join(posix.dirname(app), 'host')
+}
+
+/**
+ * The host alone, without the window, for the machines a hub installs on (docs/plans/remote-hub.md
+ * §10.2, owner decision 2 of §10.9): `host/` at the top of the package on every platform. The shim
+ * never pins these (an npm install gets the host inside its platform package already); a hub's
+ * installer fetches one beside this package instead of the platform package, so a Linux remote does
+ * not download an 81 MB AppImage to throw away. Published from the same release jobs as the platform
+ * packages (`scripts/host-package.mts`); `tooling/host-package.test.ts` holds this table to them.
+ */
+export const HOST_PACKAGES = {
+  'linux-arm64': '@centralu/host-linux-arm64',
+  'linux-x64': '@centralu/host-linux-x64',
+  'win32-x64': '@centralu/host-win32-x64',
+}
+
+/**
+ * Where `centralu serve` finds the host's `main.mjs`: in the platform package (an npm install), else
+ * in the host-only package (what a hub installed, `<data>/remote/versions/<v>/node_modules/`).
+ *
+ * `resolveRoot(name)` is the package's folder or null when it is not installed; `exists(file)` says
+ * whether a file is there. Answers `{ entry }`, or `{ missingHost: { pkg, entry } }` when a package
+ * is installed without its host, or `{ missingPackage: true }` when neither is installed.
+ */
+export function findHostEntry(platform, arch, { resolveRoot, exists }) {
+  const join = platform === 'win32' ? win32.join : posix.join
+  const target = targetFor(platform, arch)
+  const hostOnly = HOST_PACKAGES[`${platform}-${arch}`]
+  const places = []
+  if (target) places.push({ pkg: target.pkg, dir: (root) => hostDirIn(platform, join(root, target.artifact)) })
+  if (hostOnly) places.push({ pkg: hostOnly, dir: (root) => join(root, 'host') })
+  let missingHost = null
+  for (const place of places) {
+    const root = resolveRoot(place.pkg)
+    if (!root) continue
+    const entry = join(place.dir(root), 'main.mjs')
+    if (exists(entry)) return { entry }
+    missingHost ??= { pkg: place.pkg, entry }
+  }
+  return missingHost ? { missingHost } : { missingPackage: true }
+}
+
+/**
+ * How to start the app: the command, its arguments, the spawn options, and whether the
+ * launcher stays attached until it exits.
+ *
+ * - macOS goes through `open`, so LaunchServices handles the dock icon and single instance.
+ * - Linux runs the AppImage attached to the terminal, because its two usual first failures
+ *   (missing FUSE, a missing system library) explain themselves on stderr and nowhere else.
+ * - Windows starts `centralu.exe` **detached**. That is not only about handing the prompt
+ *   back: libuv puts every non-detached child in a job object that kills it when the parent
+ *   exits, so an attached app would die the moment this launcher returns, or when the
+ *   console window is closed. `centralu.exe` is a GUI-subsystem program (checked by
+ *   `scripts/release-npm.mts`), so no console window appears for it either way.
+ *   `windowsHide` stays off on purpose: it starts the process with SW_HIDE, which a GUI
+ *   program applies to its first window — the app would start invisible.
+ *   The working directory is the home folder, because a process holds its working
+ *   directory open on Windows, and that would stop the shell's folder from being renamed
+ *   or deleted (and `centralu install` from replacing the app's own folder).
+ */
+export function launchPlan(platform, app, args, home) {
+  if (platform === 'darwin') {
+    return {
+      command: 'open',
+      args: ['-a', app, ...(args.length ? ['--args', ...args] : [])],
+      options: { stdio: 'inherit' },
+      attached: true,
+    }
+  }
+  if (platform === 'win32') {
+    return {
+      command: executableIn(platform, app),
+      args,
+      options: { detached: true, stdio: 'ignore', windowsHide: false, cwd: home },
+      attached: false,
+    }
+  }
+  return { command: app, args, options: { stdio: 'inherit' }, attached: true }
+}
+
+/**
+ * Where `centralu install` puts the app on Windows, and what it writes there.
+ *
+ * The analogue of copying the bundle into `/Applications` on macOS, not of the Linux menu
+ * entry that points back into the npm package. The reason is Windows-specific: a running
+ * program's files cannot be replaced, so while the app runs from inside the npm package,
+ * `npm i -g centralu@newer` fails with EBUSY. A copy elsewhere is what lets the package
+ * update while the app is open.
+ *
+ * `%LOCALAPPDATA%\Programs` is the per-user program folder (VS Code's user installer and
+ * winget's user scope use it). No admin rights, nothing outside the user's own profile.
+ * The Start menu entry is a shortcut in the per-user Start menu folder; Windows search
+ * indexes it.
+ *
+ * `versionFile` records which package version the copy came from, so the launcher can say
+ * when the copy is behind — the exe's own version resource does not carry a prerelease tag.
+ */
+export function windowsInstall(env, home) {
+  const local = env.LOCALAPPDATA || win32.join(home, 'AppData', 'Local')
+  const roaming = env.APPDATA || win32.join(home, 'AppData', 'Roaming')
+  const dir = win32.join(local, 'Programs', APP_NAME)
+  return {
+    dir,
+    shortcut: win32.join(roaming, 'Microsoft', 'Windows', 'Start Menu', 'Programs', `${APP_NAME}.lnk`),
+    exe: win32.join(dir, 'centralu.exe'),
+    versionFile: win32.join(dir, 'centralu-version.txt'),
+  }
+}
+
+/**
+ * Which of the names in `%LOCALAPPDATA%\Programs` are copies an earlier `centralu install` renamed
+ * aside (`Centralu.old-<time>`). Only those: the folder is shared with every other per-user
+ * program, and `Centralu` itself and a `Centralu.new` being assembled are not leftovers.
+ */
+export function asideCopies(names) {
+  const prefix = `${APP_NAME}.old-`.toLowerCase()
+  return names.filter((n) => n.toLowerCase().startsWith(prefix) && /^\d+$/.test(n.slice(prefix.length)))
+}
+
+/**
+ * What `centralu install` creates, per platform. `uninstall` removes exactly these and
+ * `update` refreshes them when the first one exists.
+ */
+export function installedPaths(platform, env, home) {
+  if (platform === 'darwin') return [`/Applications/${APP_NAME}.app`]
+  if (platform === 'win32') {
+    const w = windowsInstall(env, home)
+    return [w.dir, w.shortcut]
+  }
+  return [posix.join(home, '.local/share/applications/centralu.desktop')]
+}
+
+/** The Windows folder (`%SystemRoot%`), where Windows' own programs are named from */
+export function systemRoot(env) {
+  return env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows'
+}
+
+/**
+ * A PowerShell invocation that writes the Start-menu shortcut.
+ *
+ * Windows has no file format for a shortcut that Node can write; `.lnk` is a binary shell
+ * format, and the supported way to write one is the WScript.Shell COM object. The paths go
+ * in through environment variables rather than the script text, so a profile path with a
+ * space or an apostrophe (`C:\Users\O'Brien Kim\…`) needs no quoting at all — the one way
+ * this cannot be got wrong. PowerShell is named by its full path under `%SystemRoot%` so a
+ * `powershell.exe` earlier on PATH (or in the current folder) is never the one that runs.
+ */
+export function shortcutCommand(env, { shortcut, target, workdir }) {
+  const script = [
+    '$ErrorActionPreference = "Stop"',
+    'New-Item -ItemType Directory -Force -Path (Split-Path -Parent $env:CENTRALU_SHORTCUT) | Out-Null',
+    '$s = (New-Object -ComObject WScript.Shell).CreateShortcut($env:CENTRALU_SHORTCUT)',
+    '$s.TargetPath = $env:CENTRALU_TARGET',
+    '$s.WorkingDirectory = $env:CENTRALU_WORKDIR',
+    '$s.IconLocation = "$env:CENTRALU_TARGET,0"',
+    `$s.Description = "${APP_NAME}"`,
+    '$s.Save()',
+  ].join('; ')
+  return {
+    command: win32.join(systemRoot(env), 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+    args: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+    env: { ...env, CENTRALU_SHORTCUT: shortcut, CENTRALU_TARGET: target, CENTRALU_WORKDIR: workdir },
+  }
+}
+
+/**
+ * How to run npm from the launcher (`centralu update`).
+ *
+ * On Windows `npm` is `npm.cmd`, and Node refuses to start a `.cmd` without a shell
+ * (EINVAL, since the April 2024 security releases) — and without one it would not find it
+ * either, as libuv only tries `.com` and `.exe`. So Windows goes through the shell, and
+ * because a shell re-parses its command line, every argument has to be a plain token. The
+ * version comes from the registry's response, so that is checked rather than trusted.
+ */
+export function npmCommand(platform, args) {
+  for (const a of args) {
+    if (!/^[\w@./:+-]+$/.test(a)) throw new Error(`refusing to pass an unexpected argument to npm: ${JSON.stringify(a)}`)
+  }
+  return platform === 'win32'
+    ? { command: 'npm', args, options: { stdio: 'inherit', shell: true } }
+    : { command: 'npm', args, options: { stdio: 'inherit' } }
+}
+
+export const WEBVIEW2_DOWNLOAD = 'https://developer.microsoft.com/microsoft-edge/webview2/'
+/** Microsoft's link to the Evergreen Bootstrapper itself, for someone who wants one click. */
+export const WEBVIEW2_BOOTSTRAPPER = 'https://go.microsoft.com/fwlink/p/?LinkId=2124703'
+
+/** The Evergreen WebView2 Runtime's client id, the same under every registry hive. */
+const WEBVIEW2_CLIENT = '{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}'
+
+/**
+ * Where an installed WebView2 Runtime registers itself: per machine (the 32-bit view on
+ * 64-bit Windows, which is where the installer writes), per machine on 32-bit Windows, and
+ * per user. This is Microsoft's documented detection
+ * (learn.microsoft.com/microsoft-edge/webview2/concepts/distribution, "Detect if a WebView2
+ * Runtime is already installed").
+ */
+export const WEBVIEW2_KEYS = [
+  `HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\EdgeUpdate\\Clients\\${WEBVIEW2_CLIENT}`,
+  `HKLM\\SOFTWARE\\Microsoft\\EdgeUpdate\\Clients\\${WEBVIEW2_CLIENT}`,
+  `HKCU\\Software\\Microsoft\\EdgeUpdate\\Clients\\${WEBVIEW2_CLIENT}`,
+]
+
+/** `reg.exe` by full path, for the same reason PowerShell is. */
+export function regExe(env) {
+  return win32.join(systemRoot(env), 'System32', 'reg.exe')
+}
+
+/**
+ * The `pv` value out of `reg query <key> /v pv`, or null. Microsoft's rule: the runtime is
+ * installed when `pv` exists and is neither empty nor `0.0.0.0` (an uninstall can leave
+ * the key behind with that value).
+ */
+export function parseRegPv(stdout) {
+  const m = /^\s*pv\s+REG_SZ\s+(\S*)\s*$/im.exec(String(stdout ?? ''))
+  const v = m?.[1] ?? ''
+  return v && v !== '0.0.0.0' ? v : null
+}
+
+/**
+ * Whether WebView2 is there, from a `query(key)` that returns `reg`'s stdout, `null` when
+ * the key does not exist, or `undefined` when `reg` itself could not run.
+ *
+ * Three answers, not two. "Missing" stops the launch with a message, so it has to be a
+ * positive finding — every hive was readable and none has the runtime. If `reg` could not
+ * run at all the answer is "unknown" and the app starts anyway: refusing to launch because
+ * a check broke would be worse than the blank window the check exists to explain.
+ *
+ * `WEBVIEW2_BROWSER_EXECUTABLE_FOLDER` points WebView2 at a fixed-version runtime that the
+ * registry knows nothing about; when it is set, the person has made that choice.
+ */
+export function webview2Status(env, query) {
+  if (env.WEBVIEW2_BROWSER_EXECUTABLE_FOLDER) return { state: 'present', version: 'fixed' }
+  let unknown = false
+  for (const key of WEBVIEW2_KEYS) {
+    const out = query(key)
+    if (out === undefined) {
+      unknown = true
+      continue
+    }
+    const version = parseRegPv(out)
+    if (version) return { state: 'present', version }
+  }
+  return { state: unknown ? 'unknown' : 'missing' }
+}
+
+export function webview2MissingMessage() {
+  return (
+    `${APP_NAME} needs the Microsoft Edge WebView2 Runtime, and it is not installed on this machine.\n` +
+    'Windows 11 includes it; some Windows 10 installs do not.\n' +
+    `Install the "Evergreen Bootstrapper" from ${WEBVIEW2_DOWNLOAD}\n` +
+    `(direct download: ${WEBVIEW2_BOOTSTRAPPER}),\n` +
+    'then run `centralu` again.'
+  )
+}
+
+/**
+ * What to say when the exe exits nonzero within moments of starting.
+ *
+ * The launcher is detached by then, so this is the only place a failure to start can be
+ * reported at all — a GUI program has no stderr to read. The registry check catches the
+ * usual cause before the start; this catches the rest (a runtime that is registered but
+ * broken, a blocked exe, a crash before the window).
+ */
+export function earlyExitMessage(code, home) {
+  return (
+    `${APP_NAME} exited right after starting (exit code ${code}).\n` +
+    `- If no window appeared, check the WebView2 Runtime: ${WEBVIEW2_DOWNLOAD}\n` +
+    `- The host log is ${win32.join(home, '.centralu', 'host.log')}\n` +
+    'Please report it at https://github.com/ijun17/centralu/issues/14 with that log.'
+  )
+}
+
+/**
+ * What to say when Windows refuses to replace or remove the app's files.
+ *
+ * EBUSY / EPERM on a program folder almost always means the program is running: Windows
+ * locks a running exe and the native modules the host loaded. Macs and Linux let both be
+ * replaced underneath a running process, which is why this message exists only here.
+ */
+export function busyMessage(path) {
+  return (
+    `Windows would not replace ${path} — ${APP_NAME} is probably still running.\n` +
+    'Quit it (close the window and choose Quit), then run the command again.'
+  )
+}
+
+export function isBusyError(e) {
+  return e?.code === 'EBUSY' || e?.code === 'EPERM' || e?.code === 'EACCES' || e?.code === 'ENOTEMPTY'
+}
+
+/**
+ * The command that prints the version a macOS bundle carries (`CFBundleShortVersionString`).
+ *
+ * `plutil` reads XML and binary plists alike, so nothing breaks if Tauri ever writes a binary one.
+ * The in-app update runs the same command (`installedCopyVersionSource` in
+ * `packages/agent-host/src/os.ts`, pinned to this by `updates.test.ts`), so the host and the
+ * launcher can never disagree about which version a copy is (#645).
+ */
+export function bundleVersionCommand(bundle) {
+  return { command: '/usr/bin/plutil', args: ['-extract', 'CFBundleShortVersionString', 'raw', '-o', '-', posix.join(bundle, 'Contents', 'Info.plist')] }
+}

package/bin/semver.mjs

@@ -10,8 +10,8 @@
  * Why not `.split('.').map(Number)`: that turns `0.1.0-beta.2` into
  * [0, 1, NaN, 2], and `NaN !== NaN` ends the comparison at the third slot with
  * `NaN > NaN` = false — so no beta ever saw the next beta. That is exactly how
- * `centralu update` on 0.1.0-beta.1 answered "이미 최신입니다" while beta.2 sat
- * on the registry (found the day beta.2 shipped).
+ * `centralu update` on 0.1.0-beta.1 answered "Already up to date" while
+ * beta.2 sat on the registry (found the day beta.2 shipped).
  */
 export function isNewer(a, b) {
   const [coreA, preA] = split(String(a))
@@ -62,15 +62,48 @@ export function isNewer(a, b) {
  *
  * Lives beside `isNewer` because it ships and is tested for the same reason — a launcher
  * already on someone's machine cannot be corrected later. 0.1.0-beta.1 is still out there
- * answering "이미 최신입니다" and always will be.
+ * answering "Already up to date" and always will be.
  */
 export function copyDiffers(pkgVersion, copyVersion) {
   return typeof copyVersion === 'string' && copyVersion !== '' && copyVersion !== pkgVersion
 }
 
-function split(v) {
+/*
+ * Build metadata (`+sha`) is dropped first: semver ignores it for precedence, and left in, it turned `3+build5`
+ * into NaN (and the `-` in `+build-5` into a prerelease). A leading `v` (`v1.2.3`, as a tag is written) is dropped
+ * too, or the first slot is NaN. Either NaN ends the comparison as "not newer", the #42 failure again.
+ */
+function split(raw) {
+  let v = raw.trim().replace(/^v/i, '')
+  const plus = v.indexOf('+')
+  if (plus !== -1) v = v.slice(0, plus)
   const dash = v.indexOf('-')
   const core = (dash === -1 ? v : v.slice(0, dash)).split('.').map(Number)
   const pre = dash === -1 ? null : v.slice(dash + 1)
   return [core, pre]
 }
+
+const LOCAL_BUILD = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*\.local\.[1-9]\d*$/
+
+/** A maintainer's local build: `<base>.local.N`, strict SemVer, with a prerelease base and a positive N (`scripts/local-manifest.mjs`). */
+export function isLocalBuildVersion(v) {
+  return typeof v === 'string' && v.length <= 64 && LOCAL_BUILD.test(v)
+}
+
+/**
+ * Whether the copy `centralu install` made is kept rather than replaced by `target` (#645).
+ *
+ * npm is the source of truth for releases: any released version in the copy, even a higher one, is
+ * replaced by the target, so a release pulled from `latest` (a dist-tag rollback) does not survive in
+ * /Applications. The one exception is a maintainer's local build (`<base>.local.N`, `pnpm
+ * local-update`, #610/#613) newer than the target: it waits there for "Apply now", and putting the
+ * release it was cut from over it would undo it. The copy's version must be well-formed SemVer in
+ * that exact shape; anything unreadable or malformed (`garbage`, `$(VERSION)`, an empty file) is
+ * replaced, so a corrupt plist or version file can never block every later update.
+ *
+ * `centralu install` applies this unless `--force` is given; the in-app update applies the mirror in
+ * `packages/protocol/src/semver.ts` (pinned answer to answer by `tooling/launcher-semver.test.ts`).
+ */
+export function keepsInstalledCopy(target, copyVersion) {
+  return isLocalBuildVersion(copyVersion) && isNewer(copyVersion, target)
+}

package/bin/serve-args.mjs

@@ -0,0 +1,116 @@
+/** The arguments after `centralu serve`, and its help */
+import { DEFAULT_SERVE_PORT } from './serve-port.mjs'
+
+export const SERVE_HELP = `centralu serve: run the Centralu host on this machine, without a window
+
+  centralu serve                  Start the host in the foreground, on 127.0.0.1 only
+  centralu serve --port <n>       ... on that port (kept for the next start; default ${DEFAULT_SERVE_PORT})
+  centralu serve --detach         Start it in the background, outside this session; return once it answers
+  centralu serve --stop           Ask the running host to stop, and wait until it has
+  centralu serve --window         What the Centralu window on Windows runs here: start the host if
+                                  none runs, print its port and token as a ready line, stay until
+                                  stdin ends, and leave the host running
+  centralu serve --connection     Print how to reach it as one JSON line, then exit
+  centralu serve --rotate-token   Replace the token (a running serve keeps the old one until restarted)
+  centralu serve --from <hub>     With serve or --detach: the name of the computer whose link asks,
+                                  said by a second Centralu on this data folder when it is refused
+  centralu serve --autostart on|off|remove|status
+                                  Start it when this machine starts (Linux: a systemd user unit;
+                                  Windows and WSL: a scheduled task at sign-in), stop doing that
+                                  (Windows keeps the task, without its trigger, for --detach),
+                                  remove the entry altogether, or say whether it does. None of them
+                                  starts or stops a host that runs now
+
+The data folder is ~/.centralu (CC_DATA_DIR overrides it). The app on another computer reaches
+this host through an SSH local forward, and starts it with --detach when it is not running.
+Stop a foreground one with Ctrl+C or SIGTERM, a detached one with --stop. A detached one writes
+how its start went to serve.log in the data folder; the host's own log is host.log.
+
+serve, --detach and --connection keep ~/.centralu/bin/centralu up to date: a launcher with absolute
+paths, for SSH sessions whose PATH has neither npm's global folder nor node. Not when they run
+from an install the app made over SSH, which has a launcher of its own.`
+
+/** The flags that each make serve a different command */
+const MODE_FLAGS = { '--connection': 'connection', '--rotate-token': 'rotate', '--detach': 'detach', '--stop': 'stop', '--window': 'window' }
+const FLAG_OF = { ...Object.fromEntries(Object.entries(MODE_FLAGS).map(([f, m]) => [m, f])), autostart: '--autostart' }
+
+/** What `--autostart` takes */
+export const AUTOSTART_ACTIONS = ['on', 'off', 'remove', 'status']
+
+/**
+ * The argument a detached launcher is started with: what it needs from the `--detach` that started
+ * it, which a process created through WMI does not inherit (it gets the account's default
+ * environment, not this one). Never a secret: the token stays in serve.json. Internal, not in the help.
+ */
+export const CHILD_FLAG = '--detached-child='
+
+/**
+ * What `--from` takes (#1223): a hub's name, short and of characters that cannot break the sentence a refused host says
+ * it in, nor a command line. The hub sends its own host name, cleaned the same way (`hubNameForRemote`, links/tunnel.ts)
+ */
+export const FROM_RE = /^[A-Za-z0-9._-]{1,64}$/
+
+/**
+ * What the arguments after `serve` ask for: `{ mode, port }` (plus `child` for a detached launcher,
+ * `autostart` for `--autostart`) or `{ error }`.
+ *
+ * `mode` is `serve`, `detach`, `stop`, `connection`, `rotate`, `autostart` or `help`; `port` is null
+ * when not given. `--port` goes with `serve` and `--detach` only: `--connection` has to report the
+ * port `serve` uses, not one the caller names, `--stop` stops the one that runs, and the entry
+ * `--autostart` writes starts serve on the port it recorded.
+ */
+export function parseServeArgs(argv) {
+  let mode = 'serve'
+  let port = null
+  let help = false
+  let child = null
+  let autostart = null
+  let from = null
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--autostart' || a.startsWith('--autostart=')) {
+      const raw = a === '--autostart' ? argv[++i] : a.slice('--autostart='.length)
+      if (!AUTOSTART_ACTIONS.includes(raw)) return { error: `--autostart needs on, off, remove or status (got ${raw === undefined ? 'nothing' : JSON.stringify(raw)})` }
+      if (mode !== 'serve' && mode !== 'autostart') return { error: `${FLAG_OF[mode]} and --autostart are separate commands; pass one` }
+      mode = 'autostart'
+      autostart = raw
+    } else if (Object.hasOwn(MODE_FLAGS, a)) {
+      const m = MODE_FLAGS[a]
+      if (mode !== 'serve' && mode !== m) return { error: `${FLAG_OF[mode]} and ${a} are separate commands; pass one` }
+      mode = m
+    } else if (a === '--help' || a === '-h') help = true
+    else if (a.startsWith(CHILD_FLAG)) child = a.slice(CHILD_FLAG.length)
+    else if (a === '--port' || a.startsWith('--port=')) {
+      const raw = a === '--port' ? argv[++i] : a.slice('--port='.length)
+      const n = parsePort(raw)
+      if (n === null) return { error: `--port needs a port number between 1 and 65535 (got ${raw === undefined ? 'nothing' : JSON.stringify(raw)})` }
+      port = n
+    } else if (a === '--from' || a.startsWith('--from=')) {
+      const raw = a === '--from' ? argv[++i] : a.slice('--from='.length)
+      if (typeof raw !== 'string' || !FROM_RE.test(raw)) return { error: `--from needs a computer's name: letters, digits, '.', '_' and '-' (got ${raw === undefined ? 'nothing' : JSON.stringify(raw)})` }
+      from = raw
+    } else return { error: `unknown option for serve: ${a}\n\n${SERVE_HELP}` }
+  }
+  if (help) return { mode: 'help', port }
+  if (from !== null && mode !== 'serve' && mode !== 'detach') return { error: `--from goes with \`centralu serve\` and --detach, which start a host; not with ${FLAG_OF[mode]}` }
+  if (child !== null) {
+    if (mode !== 'serve') return { error: `${CHILD_FLAG.slice(0, -1)} is how --detach starts serve, not an option of ${FLAG_OF[mode]}` }
+    return { mode, port, child, ...(from !== null ? { from } : {}) }
+  }
+  if ((mode === 'connection' || mode === 'rotate') && port !== null) {
+    return { error: '--port goes with `centralu serve`; `--connection` reports the port serve listens on' }
+  }
+  if (mode === 'stop' && port !== null) return { error: '--stop stops the serve that is running, on the port it recorded; it takes no --port' }
+  if (mode === 'window' && port !== null) return { error: '--window uses the serve that runs, or starts one on the port it recorded; it takes no --port' }
+  if (mode === 'autostart') {
+    if (port !== null) return { error: '--autostart takes no --port: the entry it writes starts serve on the port serve recorded' }
+    return { mode, port, autostart }
+  }
+  return { mode, port, ...(from !== null ? { from } : {}) }
+}
+
+function parsePort(raw) {
+  if (typeof raw !== 'string' || !/^\d{1,5}$/.test(raw)) return null
+  const n = Number(raw)
+  return n >= 1 && n <= 65535 ? n : null
+}