centralu 0.1.0-beta.22 → 0.1.0-beta.24

package/bin/centralu.mjs

@@ -23,9 +23,10 @@
  * being first exercised on someone's laptop.
  */
 import { execFileSync, spawn } from 'node:child_process'
-import { copyDiffers, isNewer } from './semver.mjs'
+import { copyDiffers, isNewer, keepsInstalledCopy } from './semver.mjs'
 import {
   asideCopies,
+  bundleVersionCommand,
   busyMessage,
   earlyExitMessage,
   executableIn,
@@ -55,6 +56,7 @@ import {
   SERVE_HELP,
 } from './serve.mjs'
 import { swapInto } from './swap.mjs'
+import { belowFloor, floorOf, oldNodeSentence } from './node-floor.mjs'
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { homedir } from 'node:os'
@@ -64,8 +66,15 @@ const require = createRequire(import.meta.url)
 const pkg = require('../package.json')
 
 const APP_NAME = 'Centralu'
+/** The oldest Node the host runs on: this package's own `engines.node` (node-floor.mjs) */
+const NODE_FLOOR = floorOf(pkg.engines.node)
 const BUNDLE = `${APP_NAME}.app`
-const INSTALLED = `/Applications/${BUNDLE}`
+/*
+ * `CENTRALU_INSTALLED_COPY` points `install` and the copy checks at another bundle path. It exists
+ * so the launcher's own tests can run `centralu install` against a temporary folder and never
+ * against the real /Applications (tooling/launcher-install.test.ts).
+ */
+const INSTALLED = process.env.CENTRALU_INSTALLED_COPY || `/Applications/${BUNDLE}`
 
 const PLATFORM = process.platform
 const HOME = homedir()
@@ -275,8 +284,22 @@ function queryRegistry(key) {
  * **Never done quietly through postinstall.** Writing silently into someone's `/Applications`
  * erodes trust, and pnpm blocks postinstall by default anyway. This is only run when the
  * person explicitly asks for it.
+ *
+ * **Never over a newer local build** (#645), unless `--force`. The in-app update runs this after
+ * `npm i -g` with the same rule (`keepsInstalledCopy`): a maintainer's local build
+ * (`0.2.0-beta.21.local.1`) waiting for "Apply now" would otherwise be replaced by npm's beta.21.
+ * Any released version is replaced, even a higher one: npm is the source of truth for releases,
+ * and a release pulled from `latest` must not survive here. The check comes before finding the app
+ * package, since keeping the copy needs nothing from it. `--force` replaces a local build on purpose.
  */
-function install() {
+function install(force) {
+  const copy = installedCopyVersion()
+  if (!force && keepsInstalledCopy(pkg.version, copy)) {
+    const where = PLATFORM === 'win32' ? WIN.dir : INSTALLED
+    console.log(`${where} holds the local build ${copy}, newer than this package (${pkg.version}), and was left as it is.`)
+    console.log('To replace it anyway: centralu install --force')
+    return
+  }
   const app = requireApp()
   if (PLATFORM === 'win32') return installWindows(app)
   if (PLATFORM !== 'darwin') return installDesktopEntry(app)
@@ -498,6 +521,7 @@ async function update() {
 
 /**
  * The version of the copy placed in /Applications. null if there is nothing to compare.
+ * (`bundleVersionCommand`: the in-app update reads it with the same command.)
  *
  * `defaults` is used because there is no guarantee Info.plist stays XML — Tauri just happens
  * to write it as XML today, and if it ever switches to a binary plist, anything reading it
@@ -517,7 +541,8 @@ function installedCopyVersion() {
   }
   if (PLATFORM !== 'darwin' || !existsSync(INSTALLED)) return null
   try {
-    const out = execFileSync('/usr/bin/defaults', ['read', join(INSTALLED, 'Contents/Info.plist'), 'CFBundleShortVersionString'], {
+    const read = bundleVersionCommand(INSTALLED)
+    const out = execFileSync(read.command, read.args, {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
     })
@@ -561,19 +586,20 @@ const HELP = `${APP_NAME} ${pkg.version}
 
   centralu              Launches the app
   centralu install      Registers it in the app list (macOS: /Applications, Linux: a menu entry,
-                        Windows: %LOCALAPPDATA%\\Programs\\Centralu and a Start menu shortcut)
+                        Windows: %LOCALAPPDATA%\\Programs\\Centralu and a Start menu shortcut).
+                        A newer local build there is kept; --force replaces it anyway
   centralu uninstall    Removes that registration (conversation history is kept)
   centralu update       Upgrades if a new version is available
   centralu serve        Runs the host alone on this machine, for the app on another computer
                         to reach over SSH (\`centralu serve --help\`)
   centralu --version    Prints the version
 
-Requires: Node 22+, and the claude or codex CLI (the app's first screen reports the status)`
+Requires: Node ${NODE_FLOOR}+, and the claude or codex CLI (the app's first screen reports the status)`
 
 const [cmd, ...rest] = process.argv.slice(2)
 switch (cmd) {
   case 'install':
-    install()
+    install(rest.includes('--force'))
     break
   case 'uninstall':
     uninstall()
@@ -598,6 +624,26 @@ switch (cmd) {
         process.exitCode = rotateToken({ env: process.env, home: HOME })
         break
       }
+      /*
+       * Before anything spawns a host: under a Node below the floor the host crashes on its first
+       * database call, with nothing in its log (issue #699). `--detach` also answers in the line the
+       * hub reads, so it can offer its managed install instead of quoting a crash. `--autostart on`
+       * writes a boot entry that would start that host. `--connection`, `--stop`, `--autostart
+       * off|status` and `--rotate-token` start no host and keep working, so the hub can still ask this
+       * machine what Node it has.
+       */
+      const startsHost = args.mode === 'serve' || args.mode === 'detach' || (args.mode === 'autostart' && args.autostart === 'on')
+      if (startsHost && belowFloor(process.versions.node, NODE_FLOOR)) {
+        const message = oldNodeSentence(process.versions.node, NODE_FLOOR)
+        console.error(`centralu serve: ${message}`)
+        if (args.mode === 'detach') {
+          const line = { v: 1, detach: { ok: false, how: null, reason: 'node_too_old', message, node: process.versions.node, floor: NODE_FLOOR } }
+          process.stdout.write(`${JSON.stringify(line)}\n`)
+        }
+        // Not process.exit: the line above is on a pipe, and exiting at once may cut it
+        process.exitCode = 1
+        break
+      }
       // A launcher `--detach` started: what it carried (the data folder, a host entry) applies before
       // anything below reads the environment
       const spec = args.child !== undefined ? decodeChildSpec(args.child) : null

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

@@ -357,3 +357,15 @@ export function busyMessage(path) {
 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

@@ -82,3 +82,28 @@ function split(raw) {
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "centralu",
-  "version": "0.1.0-beta.22",
+  "version": "0.1.0-beta.24",
   "description": "Run, watch and steer several Claude Code and Codex CLI sessions from one window",
   "license": "MIT",
   "author": "ijun17",
@@ -21,6 +21,7 @@
     "windows",
     "desktop"
   ],
+  "protocolVersion": 1,
   "type": "module",
   "bin": {
     "centralu": "bin/centralu.mjs"
@@ -29,7 +30,7 @@
     "bin"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.14.0"
   },
   "os": [
     "darwin",
@@ -37,9 +38,9 @@
     "win32"
   ],
   "optionalDependencies": {
-    "@centralu/darwin-arm64": "0.1.0-beta.22",
-    "@centralu/linux-arm64": "0.1.0-beta.22",
-    "@centralu/linux-x64": "0.1.0-beta.22",
-    "@centralu/win32-x64": "0.1.0-beta.22"
+    "@centralu/darwin-arm64": "0.1.0-beta.24",
+    "@centralu/linux-arm64": "0.1.0-beta.24",
+    "@centralu/linux-x64": "0.1.0-beta.24",
+    "@centralu/win32-x64": "0.1.0-beta.24"
   }
 }