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

package/bin/serve-window.mjs

@@ -0,0 +1,112 @@
+/**
+ * `centralu serve --window` (#1223): what the desktop window on Windows runs in place of a host of its own when
+ * `centralu serve` is installed in its data folder (`start_plan`'s `Host::Serve` in the window). One host per data
+ * folder: a linked hub's serve holds this one, or will, so the window uses that host rather than start one the folder's
+ * lock refuses.
+ */
+import { join } from 'node:path'
+import { readServeState } from './serve-files.mjs'
+import { DEFAULT_SERVE_PORT } from './serve-port.mjs'
+import { hostProvesOf, probeHost, protocolVersionOf } from './serve-host.mjs'
+import { serveFolder } from './serve-run.mjs'
+import { runDetach } from './serve-detach.mjs'
+import { startInSignIn } from './serve-autostart.mjs'
+import { say, sleep } from './serve-util.mjs'
+
+/**
+ * Makes sure the folder's serve host runs, then prints the window's ready line, `{"ready":true,"port","token","db"}`
+ * (the line a host the window starts prints), and stays until the window goes.
+ *
+ * - No host answers: one is started the way `--detach` starts it, in this Windows sign-in through the scheduled task,
+ *   so it outlives the window and the hub's link finds it (`serve --connection`).
+ * - A host in a network logon answers (the one the hub's ssh started before anyone signed in): the window uses it now,
+ *   and the sign-in task is started, whose serve moves it into this sign-in once nothing runs there
+ *   (`moveIntoSignIn`, serve-handover.mjs).
+ * - stdin is the window (it runs this with stdin a pipe): when it ends, this exits 0 and leaves the host running,
+ *   since it serves the hub's link too.
+ * - The host stops answering for `misses` polls in a row (the hand-over's gap, or it ended): this exits 1, and the
+ *   window's supervisor starts this again, which finds the new host or starts one.
+ *
+ * Resolves with the exit code. `detach`, `signIn`, `pollMs`, `misses` and `stdin` are parameters for tests.
+ */
+export async function runWindow({
+  env,
+  home,
+  entry,
+  version,
+  cliPath,
+  platform = process.platform,
+  write = (line) => process.stdout.write(line),
+  stdin = process.stdin,
+  detach = runDetach,
+  signIn = startInSignIn,
+  pollMs = 5_000,
+  misses = 3,
+}) {
+  const { dataDir } = serveFolder({ env, home, cliPath, platform })
+  const prove = hostProvesOf(entry)
+  const protocolVersion = protocolVersionOf(entry) ?? 0
+  const probe = () => {
+    const state = readServeState(dataDir)
+    return state ? probeHost({ port: state.port ?? DEFAULT_SERVE_PORT, token: state.token, protocolVersion, prove }) : Promise.resolve({ running: false })
+  }
+
+  let host = await probe()
+  if (!host.running) {
+    say(`no Centralu host runs for ${dataDir}: starting one in this Windows sign-in, which keeps running for a linked hub when the window closes`)
+    let answer = null
+    await detach({ env, home, entry, version, cliPath, platform, write: (line) => (answer = line) })
+    const d = parseLine(answer)
+    if (!d?.hostRunning) {
+      say(`could not start the host: ${d?.detach?.message ?? 'centralu serve --detach did not answer'}`)
+      return 1
+    }
+    host = await probe()
+    if (!host.running) {
+      say('the host started, then did not answer')
+      return 1
+    }
+  } else if (host.logon === 'network') {
+    const s = await signIn({ dataDir, env, home, platform }).catch((e) => ({ started: false, reason: 'error', message: e.message }))
+    say(
+      s.started
+        ? 'the host runs in a network logon (started over ssh): this window uses it, and it moves into this sign-in once nothing runs there'
+        : `the host runs in a network logon (started over ssh), and could not be moved into this sign-in (${s.message ?? s.reason})`,
+    )
+  }
+
+  const state = readServeState(dataDir)
+  write(`${JSON.stringify({ ready: true, port: state.port ?? DEFAULT_SERVE_PORT, token: state.token, db: join(dataDir, 'store.db') })}\n`)
+
+  return await new Promise((resolve) => {
+    let done = false
+    const finish = (code) => {
+      if (done) return
+      done = true
+      resolve(code)
+    }
+    stdin.once('end', () => finish(0))
+    stdin.once('close', () => finish(0))
+    stdin.resume()
+    void (async () => {
+      let missed = 0
+      while (!done) {
+        await sleep(pollMs)
+        if (done) return
+        missed = (await probe()).running ? 0 : missed + 1
+        if (missed >= misses) {
+          say(`the host for ${dataDir} stopped answering; the window starts this again`)
+          finish(1)
+        }
+      }
+    })()
+  })
+}
+
+function parseLine(text) {
+  try {
+    return JSON.parse(String(text ?? '').trim().split('\n').at(-1))
+  } catch {
+    return null
+  }
+}

package/bin/serve-windows.mjs

@@ -0,0 +1,171 @@
+/**
+ * Windows and WSL for `centralu serve`: which way a start outlives the ssh session, a Windows command
+ * line, the PowerShell that asks WMI to create a process, and the Windows programs reached by full path
+ * (from Windows itself, or through the drive a WSL distro mounts).
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { systemRoot } from './platform.mjs'
+import { runCaptured } from './serve-util.mjs'
+
+/**
+ * How `--detach` starts the launcher so that it outlives the session that asked (measured,
+ * docs/plans/remote-hub.md §10.4):
+ *
+ *   setsid  posix: a new session, no terminal, nothing from the ssh session's process group. Once
+ *           `--detach` returns, the launcher is reparented to init (the second fork of the usual
+ *           double fork); it opens no terminal, so it can never get a controlling one back
+ *   wmi     Windows: `Win32_Process.Create`. Windows' OpenSSH ends every process of a session with
+ *           it, `Start-Process` included; a process WMI creates is not part of the session
+ *   wsl     inside WSL: the same WMI call from the Windows side, creating `wsl.exe -d <distro>
+ *           --exec <launcher>`. A `setsid` launcher inside the distro survives the session but not the
+ *           distro, which WSL stops about 15 s after its last `wsl.exe` client exits; this
+ *           `wsl.exe` is a client for as long as the host runs, and ending it ends the host
+ */
+export function detachHow(platform, env, interop = wslInterop) {
+  if (platform === 'win32') return 'wmi'
+  if (platform === 'linux' && env.WSL_DISTRO_NAME && interop()) return 'wsl'
+  return 'setsid'
+}
+
+export function wslInterop() {
+  return existsSync('/proc/sys/fs/binfmt_misc/WSLInterop') || existsSync('/proc/sys/fs/binfmt_misc/WSLInterop-late')
+}
+
+/**
+ * Which Windows logon this process runs in (#1224), from `whoami /groups` as the host reads its own (`logonFromGroups`
+ * in agent-host's os.ts): `interactive` (S-1-5-4), `network` (S-1-5-2), `batch`, `service`, or null when it cannot
+ * tell. By the SIDs, which read the same in every language
+ */
+export async function ownLogon(env, run = runCaptured) {
+  const r = await run(windowsTool('wmi', env, ['System32', 'whoami.exe']), ['/groups', '/fo', 'csv', '/nh'], env).catch(() => null)
+  const out = String(r?.stdout ?? '')
+  if (/"S-1-5-4"/.test(out)) return 'interactive'
+  if (/"S-1-5-2"/.test(out)) return 'network'
+  if (/"S-1-5-3"/.test(out)) return 'batch'
+  if (/"S-1-5-6"/.test(out)) return 'service'
+  return null
+}
+
+/** A WSL distro's name for `wsl.exe -d`, refused when it could be read as anything else */
+export function wslDistro(distro) {
+  if (!/^[A-Za-z0-9._-]{1,64}$/.test(distro ?? '')) throw new Error(`not a WSL distro name: ${distro}`)
+  return distro
+}
+
+/** A Linux user's name for `wsl.exe -u`, refused when it could be read as anything else */
+export function wslUser(user) {
+  if (!/^[A-Za-z_][A-Za-z0-9_.-]{0,31}$/.test(user ?? '')) throw new Error(`cannot name the user ${user} to wsl.exe`)
+  return user
+}
+
+/**
+ * One argument for a Windows command line, as `CommandLineToArgvW` and the C runtime read it: always
+ * quoted, backslashes before the closing quote doubled. A double quote or a line break cannot be a
+ * path on Windows and is refused rather than escaped.
+ */
+export function windowsArg(arg) {
+  const s = String(arg)
+  if (/["\r\n\0]/.test(s)) throw new Error(`cannot pass ${JSON.stringify(s)} on a Windows command line`)
+  return `"${s.replace(/(\\+)$/, '$1$1')}"`
+}
+
+/**
+ * The first line of a script run by Windows PowerShell 5.1: its own module path. Started from
+ * PowerShell 7 (pwsh, a `DefaultShell` of it, a CI runner), 5.1 inherits pwsh's `PSModulePath`, whose
+ * first folder holds 7.x copies of the built-in modules that 5.1 cannot load: `Invoke-CimMethod` and
+ * `Get-ScheduledTask` are then "found in the module … but the module could not be loaded". Same line as
+ * the hub's (links/tunnel.ts, `PS_PREAMBLE`)
+ */
+export const PS_MODULE_PATH = "if ($env:PSModulePath -match '\\x5cPowerShell\\x5c') { $env:PSModulePath = \"$env:ProgramFiles\\WindowsPowerShell\\Modules;$PSHOME\\Modules\" }"
+
+/** A PowerShell expression for `s`: base64 decoded there, so no quote reaches PowerShell's parser */
+export function psText(s) {
+  return `([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${Buffer.from(String(s), 'utf8').toString('base64')}')))`
+}
+
+/** The PowerShell that asks WMI to create `commandLine`. Values cross as base64, so no quoting can break */
+export function wmiScript({ commandLine, cwd = null }) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    PS_MODULE_PATH,
+    '[Console]::OutputEncoding = [Text.Encoding]::UTF8',
+    `$a = @{ CommandLine = ${psText(commandLine)} }`,
+    ...(cwd ? [`$a.CurrentDirectory = ${psText(cwd)}`] : []),
+    // No console window when this runs from a desktop session; left out where it cannot be built
+    'try { $a.ProcessStartupInformation = New-CimInstance -ClassName Win32_ProcessStartup -ClientOnly -Property @{ ShowWindow = [uint16]0 } } catch { }',
+    'try {',
+    '  $r = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments $a',
+    "  if ($r.ReturnValue -eq 21 -and $a.ContainsKey('ProcessStartupInformation')) { $a.Remove('ProcessStartupInformation'); $r = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments $a }",
+    '  "CENTRALU-WMI $($r.ReturnValue) $($r.ProcessId)"',
+    '} catch { "CENTRALU-WMI-ERROR $($_.Exception.Message)" }',
+  ].join('\n')
+}
+
+/** `Win32_Process.Create`'s return values (Microsoft's documentation of the method) */
+const WMI_CODES = { 2: 'access denied', 3: 'insufficient privilege', 8: 'unknown failure', 9: 'path not found', 21: 'invalid parameter' }
+
+/** What the WMI script said: `{ ok: true, pid }` or `{ ok: false, message }` */
+export function parseWmiAnswer(stdout) {
+  const text = String(stdout ?? '')
+  const m = /CENTRALU-WMI (\d+) (\d*)/.exec(text)
+  if (m) {
+    const rv = Number(m[1])
+    if (rv === 0 && Number(m[2]) > 0) return { ok: true, pid: Number(m[2]) }
+    return { ok: false, message: `WMI's Win32_Process.Create returned ${rv}${WMI_CODES[rv] ? ` (${WMI_CODES[rv]})` : ''}` }
+  }
+  const e = /CENTRALU-WMI-ERROR (.*)/.exec(text)
+  if (e) return { ok: false, message: `WMI refused to create the process: ${e[1].trim()}` }
+  return { ok: false, message: 'PowerShell did not answer the WMI request' }
+}
+
+/**
+ * The sentence for a start WMI did not make. Some managed machines block process creation through
+ * WMI (Microsoft Defender's attack surface reduction rule "Block process creations originating from
+ * PSExec and WMI commands", off by default); the hub then runs the host bound to its link
+ * (docs/plans/remote-hub.md §10.9, decision 3).
+ */
+export function wmiBlockedMessage(detail) {
+  return (
+    `Windows did not start Centralu through WMI (${detail}). Some managed Windows machines block it ` +
+    '(Microsoft Defender\'s attack surface reduction rule "Block process creations originating from PSExec and WMI commands"). ' +
+    'Centralu can run there while this computer is linked instead, and stops when the link does.'
+  )
+}
+
+/** Windows PowerShell 5.1, by full path: under %SystemRoot% on Windows, through the drive WSL mounts inside a distro */
+export function windowsPowershell(how, env, mounts) {
+  return windowsTool(how, env, ['System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'], mounts)
+}
+
+/** A program under the Windows folder, by full path, from Windows or from inside a WSL distro; null when unreachable */
+export function windowsTool(how, env, rel, mounts = () => readFileSync('/proc/mounts', 'utf8')) {
+  if (how === 'wmi') return [systemRoot(env), ...rel].join('\\')
+  let text = ''
+  try {
+    text = mounts()
+  } catch {
+    // no /proc: not WSL after all
+  }
+  for (const line of text.split('\n')) {
+    const [, at, type] = line.split(' ')
+    if (!at || !(type === '9p' || type === 'drvfs')) continue
+    const candidate = [at, 'Windows', ...rel].join('/')
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+/** A script as `-EncodedCommand` takes it: UTF-16LE, in base64 */
+export function encodedCommand(script) {
+  return Buffer.from(script, 'utf16le').toString('base64')
+}
+
+/**
+ * Runs `script` in the Windows PowerShell at `ps` and reads what it printed with `parse` (`{ ok, … }`). When it printed
+ * nothing and PowerShell itself complained (a policy, a module it could not load), the answer is the last line of that.
+ */
+export async function askPowershell(ps, script, env, parse, run = runCaptured) {
+  const r = await run(ps, ['-NoProfile', '-NonInteractive', '-EncodedCommand', encodedCommand(script)], env)
+  const a = parse(r.stdout)
+  return a.ok || r.stdout.trim() || !r.stderr.trim() ? a : { ok: false, message: r.stderr.trim().split(/\r?\n/).at(-1) }
+}

package/bin/serve.mjs

@@ -0,0 +1,37 @@
+/**
+ * `centralu serve`: the host without the app, for the remote mode's first phase (#82).
+ *
+ * The person starts this by hand on another machine (an SSH server, later a laptop). It runs the
+ * same bundled host the app runs (`resources/host/main.mjs`, on the system Node), with no window
+ * and no keeper, bound to 127.0.0.1 only. The app on the person's own computer reaches it through
+ * an SSH local forward, so nothing ever listens on a public interface. The design and its limits
+ * are in docs/agent-host.md §4.7; the trust argument in docs/security-boundaries.md.
+ *
+ * `centralu serve --connection` is the one question the client asks over `ssh <target>`: where to
+ * forward and how to authenticate. It answers with one JSON line on stdout and nothing else.
+ *
+ * Everything here takes its inputs as arguments (environment, home, platform) instead of reading
+ * `process`, so `tooling/launcher-serve.test.ts` can import it: `centralu.mjs` runs a command at
+ * import time and cannot be imported by a test. package.json "files" lists the whole bin/
+ * directory, so this ships automatically.
+ *
+ * This file is the launcher's `serve` as one module, for `centralu.mjs`, the tests, and the hub's
+ * installer (which imports an installed version's `serve.mjs` for `managedLauncherScript`). The code
+ * lives beside it, one concern per file: the arguments (`serve-args.mjs`), the files in the data
+ * folder (`serve-files.mjs`), the port (`serve-port.mjs`), the launchers and the managed install
+ * (`serve-install.mjs`), the host and its socket (`serve-host.mjs`), the foreground serve
+ * (`serve-run.mjs`), `--detach` and `--stop` (`serve-detach.mjs`), `--autostart`
+ * (`serve-autostart.mjs`), Windows, WSL and PowerShell (`serve-windows.mjs`), and small helpers
+ * (`serve-util.mjs`).
+ */
+export { SERVE_STATE_FILE, SERVE_LOG_FILE, SERVE_PID_FILE, serveDataDir, readServeState, ensureServeState, recordServePort, rotateServeToken, heldHere, lockHolderIsAlive, processStartTime, lockHolder, lockHolderPid, readServePid, SERVE_STOPPED_FILE, SERVE_LOGS_KEPT, markStopped, readStopped, rotateServeLog } from './serve-files.mjs'
+export { detachHow, windowsArg, wmiScript, parseWmiAnswer, wmiBlockedMessage, windowsPowershell, ownLogon } from './serve-windows.mjs'
+export { DEFAULT_SERVE_PORT, SERVE_PORT_TRIES, chooseServePort, listensHere, parseNetstatListening } from './serve-port.mjs'
+export { SERVE_HELP, AUTOSTART_ACTIONS, parseServeArgs } from './serve-args.mjs'
+export { launcherScript, ensureLauncher, remoteLayout, parsePointer, installInfo, managedLauncherScript } from './serve-install.mjs'
+export { protocolVersionOf, connectionLine, hostEnv, hostCommand, readyPort, mismatchServerVersion, hostProvesOf, probeHost, askHostToStop, askHostRpc, serveFrom, takesTokenOnStdin, tokenLine } from './serve-host.mjs'
+export { stopServedHost, moveIntoSignIn, HANDOVER_WAIT_MS } from './serve-handover.mjs'
+export { runWindow } from './serve-window.mjs'
+export { AUTOSTART_FILE, AUTOSTART_ENV, autostartHow, autostartUnsupported, pathKey, autostartName, autostartLauncher, systemdUnit, taskActionScript, taskScript, parseTaskAnswer, readAutostartMark, autostartInfo, lingerMessage, runAutostart, startInSignIn } from './serve-autostart.mjs'
+export { printConnection, runServe, rotateToken } from './serve-run.mjs'
+export { CARRIED_ENV, encodeChildSpec, decodeChildSpec, startDetached, runDetach, runDetachedChild, runStop } from './serve-detach.mjs'

package/bin/swap.mjs

@@ -0,0 +1,48 @@
+/**
+ * Replacing an installed copy of the app without a moment where there is none.
+ *
+ * Lives apart from `centralu.mjs` for the same reason `platform.mjs` does: the launcher runs a
+ * command at import time, so a test cannot import it. The paths come in as arguments, so
+ * `tooling/launcher-swap.test.ts` runs this against temporary folders instead of `/Applications`.
+ */
+import { existsSync, renameSync, rmSync } from 'node:fs'
+
+/**
+ * Puts a new copy at `target`: `fill(staging)` writes it beside the old one, the old one is
+ * renamed aside, the new one is renamed in, and only then is the old one deleted.
+ *
+ * The old copy is never deleted before the new one is complete. Deleting first and copying
+ * after left a person whose copy failed (a full disk, a permission, an interrupted `ditto`)
+ * with no app at all, from a command they ran to update it. A copy that fails here leaves the
+ * old install untouched, and a rename that fails puts the old one back.
+ *
+ * Returns whether something was replaced, and where the old copy was left if it could not be
+ * deleted (null when it was).
+ */
+export function swapInto(target, fill, now = Date.now()) {
+  const staging = `${target}.new`
+  const aside = `${target}.old-${now}`
+  rmSync(staging, { recursive: true, force: true })
+  try {
+    fill(staging)
+  } catch (e) {
+    rmSync(staging, { recursive: true, force: true })
+    throw e
+  }
+  const replaced = existsSync(target)
+  if (replaced) renameSync(target, aside)
+  try {
+    renameSync(staging, target)
+  } catch (e) {
+    if (replaced) renameSync(aside, target)
+    rmSync(staging, { recursive: true, force: true })
+    throw e
+  }
+  if (!replaced) return { replaced, leftAt: null }
+  try {
+    rmSync(aside, { recursive: true, force: true })
+    return { replaced, leftAt: null }
+  } catch {
+    return { replaced, leftAt: aside }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "centralu",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.41",
   "description": "Run, watch and steer several Claude Code and Codex CLI sessions from one window",
   "license": "MIT",
   "author": "ijun17",
@@ -18,8 +18,10 @@
     "agent",
     "macos",
     "linux",
+    "windows",
     "desktop"
   ],
+  "protocolVersion": 1,
   "type": "module",
   "bin": {
     "centralu": "bin/centralu.mjs"
@@ -28,15 +30,17 @@
     "bin"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.14.0"
   },
   "os": [
     "darwin",
-    "linux"
+    "linux",
+    "win32"
   ],
   "optionalDependencies": {
-    "centralu-darwin-arm64": "0.1.0-beta.4",
-    "centralu-linux-arm64": "0.1.0-beta.4",
-    "centralu-linux-x64": "0.1.0-beta.4"
+    "@centralu/darwin-arm64": "0.1.0-beta.41",
+    "@centralu/linux-arm64": "0.1.0-beta.41",
+    "@centralu/linux-x64": "0.1.0-beta.41",
+    "@centralu/win32-x64": "0.1.0-beta.41"
   }
 }