wherdr 1.3.3 → 2.0.0

package/bin/lib/commands.mjs

@@ -10,7 +10,8 @@ import { pathToFileURL } from 'node:url'
 import { BIN, CliError, SERVER, VERSION, bad, c, homebrewInstall, localUrl, ok, portTaken, probe, row, say, serverEnv, settingsFile, warn, wherdrDir, withSettings } from './core.mjs'
 import { RUNTIME_HELP, findRuntime, isBun, runtimeOk, runtimeVersion, temporaryInstall } from './runtime.mjs'
 import { brewDoctor, brewRedirect, brewService, brewStatusRows } from './brew.mjs'
-import { controlService, installService, serviceFile, servicePlatform, serviceState, uninstallService } from './service.mjs'
+import { controlService, enableLinger, installService, lingerOn, serviceFile, servicePlatform, serviceState, uninstallService } from './service.mjs'
+import { loginShellPath, userPath } from './userpath.mjs'
 import { refreshSkill } from './skill.mjs'
 import { LINKS, inspect, publishCommand, reachable } from './tailnet.mjs'
 
@@ -33,7 +34,7 @@ Commands:
 
 Options:
   --port <n>        Listening port (default: 7683, or $PORT)
-  --host <addr>     Listening address (default: 127.0.0.1, or $HOST). Keep it on loopback.
+  --host <addr>     Listening address (default: 127.0.0.1, or $HOST): loopback or this machine's tailnet address.
   --data-dir <dir>  Passkeys, push keys and settings (default: ~/wherdr/data, or $DATA_DIR)
   --session <name>  Named Herdr session to drive (default: Herdr's default session)
   -v, --version     Print the version
@@ -224,7 +225,7 @@ export async function stop(opts, { quiet = false } = {}) {
   }
   if (quiet) return false
   const other = await probe(ctx.port, ctx.host)
-  if (other) warn(`the wherdr on port ${ctx.port} was not started by \`wherdr start\` (Docker, plugin, a terminal…): left running.`)
+  if (other) warn(`the wherdr on port ${ctx.port} was not started by \`wherdr start\` (plugin, a terminal…): left running.`)
   else say('wherdr is not running.')
   return false
 }
@@ -254,7 +255,7 @@ export async function status(opts) {
   const hb = brew && brewStatusRows(brew)
   say(`${c.bold('wherdr')} ${VERSION}`)
   row('Address', answer === 'wherdr' ? `${c.green('●')} ${c.cyan(ctx.url)} answers` : answer ? `${c.yellow('●')} port ${ctx.port} is taken by another program` : `${c.dim('○')} port ${ctx.port} free: not running`)
-  row('Process', hb?.process ? hb.process : svc.running ? 'login service' : pid ? `pid ${pid} (wherdr start)` : answer === 'wherdr' ? 'started another way (Docker, plugin, a terminal…)' : 'none')
+  row('Process', hb?.process ? hb.process : svc.running ? 'login service' : pid ? `pid ${pid} (wherdr start)` : answer === 'wherdr' ? 'started another way (plugin, a terminal…)' : 'none')
   row('Service', hb ? hb.service : svc.installed ? `installed (${serviceFile()})${svc.running ? '' : ', not running'}` : 'not installed · wherdr service install')
   row('Data', ctx.env.DATA_DIR)
   row('Log', hb ? hb.log : ctx.files.log)
@@ -403,20 +404,51 @@ export async function service(opts) {
   const runtime = findRuntime(ctx.env)
   if (!runtime) throw new CliError(RUNTIME_HELP)
   // The background server of `wherdr start` would hold the port.
-  if (await stop(opts, { quiet: true })) ok('background wherdr stopped (the service takes over).')
+  const stopped = await stop(opts, { quiet: true })
+  if (stopped) ok('background wherdr stopped (the service takes over).')
   await checkPort(ctx)
   remember(ctx)
   const args = [bin, 'run', '--port', ctx.port, '--host', ctx.host, '--data-dir', ctx.env.DATA_DIR]
   if (ctx.env.HERDR_WEB_SESSION) args.push('--session', ctx.env.HERDR_WEB_SESSION)
-  const PATH = [...new Set([path.dirname(runtime), path.join(os.homedir(), '.local/bin'), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'])].join(':')
+  // launchd and systemd do not see the shell's PATH: the service gets the
+  // user's, so agents in user folders are found by the Board's commands.
+  const PATH = servicePath(runtime, ctx.env)
   const env = { PATH, WHERDR_DIR: ctx.dir, WHERDR_RUNTIME: runtime }
-  for (const k of ['APP_URL', 'HERDR_BIN', 'HOST_LABEL', 'CLAUDE_CONFIG_DIR', 'WHERDR_SKILL']) if (ctx.env[k]) env[k] = ctx.env[k]
-  const file = installService({ runtime, args, env, log: ctx.files.log })
+  for (const k of ['APP_URL', 'HERDR_BIN', 'HOST_LABEL', 'CLAUDE_CONFIG_DIR', 'WHERDR_SKILL', 'HERDR_PROJECTS_DATA_DIR']) if (ctx.env[k]) env[k] = ctx.env[k]
+  let file
+  try {
+    file = installService({ runtime, args, env, log: ctx.files.log })
+  } catch (e) {
+    // wherdr was stopped above for the service to take over: started again,
+    // as it was (the previous service, or in the background).
+    let back = ''
+    if (stopped) {
+      try {
+        await start(opts)
+        back = '\n  wherdr was started again as before.'
+      } catch (err) { back = `\n  wherdr could not be started again: ${err.message}` }
+    }
+    throw new CliError(`${e.message}${back}`)
+  }
   ok(`login service installed: ${file}`)
   say(c.dim(`    ${runtime} ${args.join(' ')}`))
   if (await waitUp(ctx, () => true)) ok(`wherdr runs: ${c.cyan(ctx.url)} (and starts at every login)`)
   else failWithLog(`the service did not answer on port ${ctx.port} after 45 s.`, ctx.files.log, 0)
-  if (servicePlatform() === 'systemd') say(c.dim('    To keep it running while you are logged out: loginctl enable-linger'))
+  if (servicePlatform() === 'systemd') {
+    // Without lingering, systemd stops the user's services at logout (and
+    // starts them only at the next login): a server reached over SSH or from
+    // the phone would go away. Allowed for one's own user, without sudo, on
+    // most systems; otherwise the command to run is printed.
+    const linger = enableLinger()
+    if (linger.ok) ok(linger.already ? 'lingering is on: wherdr keeps running when you log out.' : 'lingering enabled (loginctl enable-linger): wherdr keeps running when you log out.')
+    else warn(`lingering is off: wherdr stops when you log out. To keep it running, run once: ${c.cyan(`sudo loginctl enable-linger ${os.userInfo().username}`)}`)
+  }
+}
+
+// The service's PATH: the runtime's folder, then the user's PATH (the login
+// shell's, asked once, herdr-projects' record and the usual folders).
+export function servicePath(runtime, env = process.env, { home = os.homedir(), login = loginShellPath(env), exists } = {}) {
+  return userPath({ env, home, first: [path.dirname(runtime)], login, exists })
 }
 
 // ---------------------------------------------------------------- doctor
@@ -478,6 +510,9 @@ export async function doctor(opts) {
   else if (!svc.installed) warn('Login service: not installed (wherdr service install starts wherdr at login).')
   else if (svc.running) ok(`Login service: running (${serviceFile()})`)
   else fail(`Login service: installed but not running (${serviceFile()}). See wherdr logs.`)
+  if (!brew && svc.installed && servicePlatform() === 'systemd' && !lingerOn()) {
+    warn(`Lingering is off: wherdr stops when you log out (sudo loginctl enable-linger ${os.userInfo().username}).`)
+  }
 
   try {
     mkdirSync(ctx.env.DATA_DIR, { recursive: true })

package/bin/lib/panel.mjs

@@ -1,10 +1,3 @@
-// `wherdr panel`: the Herdr plugin's "panel" action opens it in a popup.
-// The state, and two main keys: O opens wherdr, P opens its phone setup
-// (Settings › Phone) in the browser. The other commands stay as a fallback,
-// in a quieter line. Refreshed every few seconds.
-//
-// Commands run through a controller: `wherdr` itself, or the Herdr plugin
-// script when WHERDR_CONTROL holds its argv as JSON (it knows Docker mode).
 import { spawn } from 'node:child_process'
 import os from 'node:os'
 import path from 'node:path'
@@ -43,7 +36,7 @@ export async function tailnet(port) {
 
 export async function gather(ctx, env = process.env, net = null) {
   const answer = await probe(ctx.port, ctx.host)
-  const mode = env.WHERDR_MODE === 'docker' ? 'docker' : 'native'
+  const mode = 'native'
   return {
     version: VERSION,
     mode,
@@ -55,7 +48,7 @@ export async function gather(ctx, env = process.env, net = null) {
     port: ctx.port,
     answer,
     pid: livePid(ctx.files.pid),
-    service: mode === 'docker' ? { installed: false, running: false } : serviceState(),
+    service: serviceState(),
     serviceFile: serviceFile(),
     dir: ctx.dir,
     tailnet: net ?? await tailnet(ctx.port),
@@ -95,14 +88,13 @@ export function render(state, qrText = '') {
   out.push(`  ${MAIN_KEYS.map(([k, label]) => `${c.bold(k.toUpperCase())} ${label}`).join('    ')}`)
   out.push('')
   out.push(`  ${c.dim(OTHER_KEYS.map(([k, label]) => `${k.toUpperCase()} ${label}`).join('  '))}`)
-  out.push(`  ${c.dim(`${state.mode === 'docker' ? 'Docker' : `native · ${state.runtime}`} · auto-start ${autostart(state)}`)}`)
+  out.push(`  ${c.dim(`native · ${state.runtime} · auto-start ${autostart(state)}`)}`)
   if (state.hotkey) out.push(`  ${c.dim(`Herdr key ${state.hotkey} opens this panel`)}`)
   out.push(`  ${c.dim(removeHint(state))}`)
   return out.join('\n')
 }
 
 function autostart(state) {
-  if (state.mode === 'docker') return 'yes · Docker restart policy'
   if (state.service.installed) return `at login (${state.service.running ? 'running' : 'not running'}) · A turns it off`
   if (state.plugin) return 'with Herdr (plugin startup) · A: also at login'
   return 'no · A: at login'

package/bin/lib/service.mjs

@@ -1,7 +1,7 @@
 // `wherdr service install|uninstall`: start wherdr at login, with the absolute
 // path of the runtime. macOS: a LaunchAgent; Linux: a systemd --user unit.
 import { spawnSync } from 'node:child_process'
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 
@@ -88,11 +88,24 @@ export function serviceState(home = os.homedir()) {
   return { installed: true, running: sh('systemctl', ['--user', 'is-active', '--quiet', UNIT]).ok }
 }
 
-export function installService(spec, home = os.homedir()) {
+// A failure leaves things as they were: the previous service file back (and
+// loaded again), or no file at all, so a later run does not take a half-made
+// service for an installed one. `run` is injectable for the tests.
+export function installService(spec, home = os.homedir(), run = sh) {
   const file = serviceFile(home)
   if (!file) throw new Error(`no login service on ${process.platform}: keep wherdr running with your own service manager.`)
   mkdirSync(path.dirname(file), { recursive: true })
   mkdirSync(path.dirname(spec.log), { recursive: true })
+  const before = existsSync(file) ? readFileSync(file, 'utf8') : null
+  try {
+    return writeService(file, spec, run)
+  } catch (e) {
+    restoreService(file, before, run)
+    throw e
+  }
+}
+
+function writeService(file, spec, sh) {
   if (servicePlatform() === 'launchd') {
     writeFileSync(file, launchdPlist(spec))
     sh('launchctl', ['bootout', `${domain()}/${LABEL}`])
@@ -109,6 +122,18 @@ export function installService(spec, home = os.homedir()) {
   return file
 }
 
+function restoreService(file, before, sh) {
+  try {
+    if (before === null) rmSync(file, { force: true })
+    else writeFileSync(file, before)
+    if (servicePlatform() === 'launchd') {
+      if (before !== null) sh('launchctl', ['bootstrap', domain(), file])
+    } else {
+      sh('systemctl', ['--user', 'daemon-reload'])
+    }
+  } catch { /* best effort: the original error is the one to report */ }
+}
+
 export function uninstallService(home = os.homedir()) {
   const file = serviceFile(home)
   if (!file || !existsSync(file)) return null
@@ -119,6 +144,20 @@ export function uninstallService(home = os.homedir()) {
   return file
 }
 
+// systemd: is lingering on for this user (its services run without a login)?
+export function lingerOn(user = os.userInfo().username, run = sh) {
+  const r = run('loginctl', ['show-user', user, '--property=Linger', '--value'])
+  return r.ok && r.out.trim() === 'yes'
+}
+
+// Turns lingering on for this user, without sudo (logind allows it for one's
+// own user on most systems). { ok, already }: ok false when it was refused.
+export function enableLinger(user = os.userInfo().username, run = sh) {
+  if (lingerOn(user, run)) return { ok: true, already: true }
+  const r = run('loginctl', ['enable-linger', user])
+  return { ok: r.ok && lingerOn(user, run), already: false }
+}
+
 // start | stop | restart through the service manager.
 export function controlService(action) {
   if (servicePlatform() === 'launchd') {

package/bin/lib/skill.mjs

@@ -1,4 +1,4 @@
-// The shell helper is also used without Node by the Docker / Herdr installer.
+// The shell helper is also used without Node by the Herdr installer.
 import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 

package/bin/lib/tailnet.d.mts

@@ -4,7 +4,6 @@ export interface PhoneAddress { url: string, served: boolean, httpsPort: string,
 export interface Tailnet {
   installed: boolean
   bin?: string | null
-  // Tailscale's socket, when the state was read there (no CLI: Docker).
   socket?: string | null
   name?: string | null
   connected?: boolean
@@ -30,12 +29,16 @@ export function servedPorts(serveJson: string): string[]
 export function publishCommand(port: string | number, httpsPort?: string | number): string
 export function publishArgs(port: string | number): string[]
 export function unpublishArgs(httpsPort: string): string[]
-export function tailnetUrl(text: unknown): string | null
 export function serveError(output: string): { code: ServeErrorCode, link: string } | null
 export function inspect(port: string | number, bin?: string | null, socket?: string | null): Promise<Tailnet>
-export function tailnetDomain(resolvConf: string): string | null
 export function reachable(url: string, timeoutMs?: number): Promise<Reach>
 export function healthReach(status: number, text: string): 'ok' | 'host' | null
 export function probe(url: string, timeoutMs?: number): Promise<Probe>
 export function failureCause(err: unknown): ReachCause
 export function runTailscale(bin: string, args: string[], timeoutMs?: number): Promise<{ code: number, output: string }>
+export interface TailnetPeers { readable: boolean, state: string | null, running: boolean, selfIps: string[], peerIps: string[] }
+export interface TailnetFacts extends Omit<TailnetPeers, 'state'> { installed: boolean, funnel: boolean | null }
+export function tailnetPeers(statusJson: string): TailnetPeers
+export function targetPort(target: unknown): number | null
+export function funnelExposes(port: string | number, serveJson: string): boolean | null
+export function tailnetFacts(port: string | number, bin?: string | null, socket?: string | null): Promise<TailnetFacts>

package/bin/lib/tailnet.mjs

@@ -27,11 +27,7 @@ export function tailscaleBin(env = process.env, exists = existsSync) {
   return dirs.find(p => exists(p)) || null
 }
 
-// Tailscale's own socket on Linux. Its local API answers the same JSON as the
-// CLI: a Docker container has no `tailscale` command, but docker-compose.yml
-// mounts this folder, so wherdr reads the state there. Anyone may read; the
-// API also accepts changes from Tailscale's operator, but wherdr only ever
-// sends GET requests to it (localApi below).
+// The local read-only API is useful when the CLI is absent from PATH.
 export const TAILSCALED_SOCKET = '/var/run/tailscale/tailscaled.sock'
 export function tailscaledSocket(env = process.env, exists = existsSync) {
   const file = env.WHERDR_TAILSCALED_SOCKET || TAILSCALED_SOCKET
@@ -67,6 +63,75 @@ export function tailnetStatus(statusJson) {
   }
 }
 
+// What wherdr's network check needs from `tailscale status --json` (with
+// peers): whether the answer could be read at all, Tailscale's state, this
+// machine's tailnet addresses and those of its peers. Read from Tailscale
+// itself, never guessed from an interface address in 100.64.0.0/10.
+// readable: false for an empty or broken answer (a failed command, a socket
+// that did not answer): nothing is known then, not "stopped".
+export function tailnetPeers(statusJson) {
+  let s = null
+  try { s = JSON.parse(statusJson) } catch {}
+  const ips = node => (Array.isArray(node?.TailscaleIPs) ? node.TailscaleIPs.filter(ip => typeof ip === 'string') : [])
+  const readable = Boolean(s && typeof s === 'object' && typeof s.BackendState === 'string')
+  return {
+    readable,
+    state: readable ? s.BackendState : null,
+    running: readable && s.BackendState === 'Running',
+    selfIps: readable ? ips(s.Self) : [],
+    peerIps: readable ? Object.values(s.Peer || {}).flatMap(ips) : [],
+  }
+}
+
+// States in which tailscaled relays nothing, Funnel included.
+const IDLE_STATES = new Set(['Stopped', 'NeedsLogin', 'NoState', 'NeedsMachineAuth'])
+
+// The port a Serve or Funnel target leads to, or null when it cannot be told
+// ("127.0.0.1:7683", "0.0.0.0:7683", "[::1]:7683", "http://localhost:7683/x",
+// "https+insecure://host", "7683"…). The host is deliberately not compared:
+// 0.0.0.0, another spelling of loopback, a LAN address of this machine or a
+// name may all reach wherdr, so only the port can rule a target out.
+export function targetPort(target) {
+  const t = String(target ?? '').trim()
+  if (/^\d{1,5}$/.test(t)) return Number(t)
+  const m = /^(?:([a-z][a-z0-9+.-]*):\/\/)?(\[[^\]]*\]|[^/:\s]*)(?::(\d{1,5}))?(?:[/?#].*)?$/i.exec(t)
+  if (!m || !m[2]) return null
+  if (m[3]) return Number(m[3])
+  const scheme = (m[1] || '').toLowerCase().replace(/\+insecure$/, '')
+  return scheme === 'http' ? 80 : scheme === 'https' ? 443 : null
+}
+
+export function funnelExposes(port, serveJson) {
+  let config = null
+  try { config = JSON.parse(serveJson) } catch {}
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return null
+  const reaches = target => targetPort(target) === null || targetPort(target) === Number(port)
+  for (const part of [config, ...Object.values(config.Foreground || {})]) {
+    for (const [hostPort, on] of Object.entries(part?.AllowFunnel || {})) {
+      if (!on) continue
+      const tcpPort = hostPort.slice(hostPort.lastIndexOf(':') + 1)
+      const tcp = part?.TCP?.[tcpPort]
+      if (tcp?.TCPForward !== undefined && reaches(tcp.TCPForward)) return true
+      const handlers = Object.values(part?.Web?.[hostPort]?.Handlers || {})
+      if (handlers.some(h => h && typeof h === 'object' && h.Proxy !== undefined && reaches(h.Proxy))) return true
+      // Funnel on a port with neither a TCP forward nor web handlers we can read.
+      if (tcp?.TCPForward === undefined && !part?.Web?.[hostPort] && !tcp?.HTTPS && !tcp?.HTTP) return true
+    }
+  }
+  return false
+}
+
+// Only a valid reading may prove the absence of Funnel on this port.
+export async function tailnetFacts(port, bin = tailscaleBin(), socket = bin ? null : tailscaledSocket()) {
+  if (!bin && !socket) return { installed: false, readable: true, running: false, selfIps: [], peerIps: [], funnel: false }
+  const run = args => exec(bin, args, { encoding: 'utf8', timeout: 8000 }).then(r => r.stdout, () => '')
+  const { state, ...peers } = tailnetPeers(bin ? await run(['status', '--json']) : await localApi(socket, 'status'))
+  if (!peers.readable) return { installed: true, ...peers, funnel: null }
+  if (IDLE_STATES.has(state)) return { installed: true, ...peers, funnel: false }
+  const serve = bin ? await run(['serve', 'status', '--json']) : await localApi(socket, 'serve-config')
+  return { installed: true, ...peers, funnel: funnelExposes(port, serve) }
+}
+
 // The HTTPS entries of a serve configuration that proxy to wherdr's local
 // port on this machine's own name: [{ hostPort, httpsPort, funnel }], or null
 // when the configuration could not be read (Tailscale stopped, not JSON).
@@ -120,22 +185,10 @@ export function servedPorts(serveJson) {
   } catch { return [] }
 }
 
-// The command that publishes wherdr's port, as typed by hand (Docker mode).
-// `httpsPort`: the tailnet port, wherdr's own by default.
 export const publishCommand = (port, httpsPort = port) => `tailscale serve --bg --https=${httpsPort} http://127.0.0.1:${port}`
 export const publishArgs = port => ['serve', '--bg', `--https=${port}`, `http://127.0.0.1:${port}`]
 export const unpublishArgs = httpsPort => ['serve', `--https=${httpsPort}`, 'off']
 
-// A tailnet address typed by hand: https://machine.tailnet.ts.net[:port]/ → its
-// normalized form, or null.
-export function tailnetUrl(text) {
-  try {
-    const u = new URL(String(text || '').trim())
-    if (u.protocol !== 'https:' || !/^[a-z0-9-]+(\.[a-z0-9-]+)*\.ts\.net$/i.test(u.hostname) || u.username || u.password) return null
-    return `https://${u.host.toLowerCase()}/`
-  } catch { return null }
-}
-
 // A failed `tailscale serve` → { code, link } for the known causes, else null.
 // code: 'operator' (Linux: the user may not change Tailscale's settings),
 // 'https' (no HTTPS certificates on the tailnet), 'offline' (not connected).
@@ -148,9 +201,6 @@ export function serveError(output) {
   return null
 }
 
-// Tailscale's state for wherdr's port: { installed, bin, socket, connected,
-// https, name, phone, taken, served }. Read with the CLI, or without one
-// (Docker) from Tailscale's socket.
 export async function inspect(port, bin = tailscaleBin(), socket = bin ? null : tailscaledSocket()) {
   if (!bin && !socket) return { installed: false }
   const run = args => exec(bin, args, { encoding: 'utf8', timeout: 8000 }).then(r => r.stdout, () => '')
@@ -162,18 +212,6 @@ export async function inspect(port, bin = tailscaleBin(), socket = bin ? null :
   return { installed: true, bin, socket, ...status, phone, taken, served: servedAddresses(status.name, port, serve) }
 }
 
-// The tailnet's DNS suffix (tailnet.ts.net) from /etc/resolv.conf's search
-// line: a Docker container copies it from the host when MagicDNS is on.
-export function tailnetDomain(resolvConf) {
-  for (const line of String(resolvConf || '').split('\n')) {
-    const m = /^\s*search\s+(.+)$/.exec(line)
-    const hit = m?.[1].split(/\s+/).find(d => /^[a-z0-9-]+\.ts\.net$/i.test(d))
-    if (hit) return hit.toLowerCase()
-  }
-  return null
-}
-
-// Tailscale's DNS (MagicDNS): a Docker container does not use it, but reaches it.
 const MAGIC_DNS = '100.100.100.100'
 
 // The system's lookup, then MagicDNS for *.ts.net names.

package/bin/lib/userpath.d.mts

@@ -0,0 +1,14 @@
+// Types of userpath.mjs, for the server (server/utils/env.ts, projectsTasks.ts).
+export const USER_BIN_DIRS: string[]
+export const LEAD_BIN_DIRS: string[]
+export const TAIL_BIN_DIRS: string[]
+export const SYSTEM_BIN_DIRS: string[]
+export function mergePath(...parts: Array<string | string[] | undefined | null>): string
+export function knownBinDirs(home?: string, exists?: (p: string) => boolean): string[]
+export function projectsDataDir(env?: NodeJS.ProcessEnv, home?: string): string
+export function projectsEnvPath(env?: NodeJS.ProcessEnv, home?: string): string
+export function pathFromEnvOutput(text: string): string
+export function loginShellPath(env?: NodeJS.ProcessEnv, run?: unknown): string
+export function userPath(opts?: { env?: NodeJS.ProcessEnv, home?: string, first?: string[], login?: string, exists?: (p: string) => boolean }): string
+export const JSON_PATH_AWK: string
+export const USER_PATH_SH: string

package/bin/lib/userpath.mjs

@@ -0,0 +1,142 @@
+// The PATH of the user, for what wherdr runs without a login shell: the login
+// service (systemd --user, launchd), the server it starts, and the
+// herdr-projects commands of the Board, on this machine and over SSH.
+//
+// systemd and launchd start wherdr with a short system PATH, and an SSH command
+// gets the remote shell's non-login PATH: agents installed in a user folder
+// (~/.local/bin, ~/.bun/bin, ~/.cargo/bin, ~/.npm-global/bin, Homebrew) are
+// then not found, and herdr-projects refuses with "claude is not installed
+// here". herdr-projects only widens its own PATH when Herdr runs it as a plugin
+// command; wherdr runs it directly. So wherdr gives it the PATH an interactive
+// login shell would have, in this order:
+//   1. at `wherdr service install`: the PATH of the login shell, asked once;
+//   2. the PATH herdr-projects recorded from a login shell
+//      ($HERDR_PROJECTS_DATA_DIR/env.json, default ~/.herdr-projects/data);
+//   3. the usual user folders and Homebrew's, when they exist;
+//   4. the PATH it was given;
+//   5. the system folders, when they exist.
+// The user's own folders come before the system ones, as in their shell: an
+// old system-wide copy of an agent never wins over theirs. Each folder once.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+// Where agent CLIs install themselves for one user (relative to $HOME).
+export const USER_BIN_DIRS = ['.local/bin', '.bun/bin', '.cargo/bin', '.npm-global/bin', '.deno/bin', '.volta/bin', 'bin']
+// Homebrew (Apple silicon, Intel, Linux) and /usr/local/bin, where a user's
+// own installs go too: before the PATH given, with the user folders.
+export const LEAD_BIN_DIRS = ['/opt/homebrew/bin', '/opt/homebrew/sbin', '/home/linuxbrew/.linuxbrew/bin', '/usr/local/bin']
+// The system's own: after the PATH given.
+export const TAIL_BIN_DIRS = ['/usr/bin', '/bin', '/usr/local/sbin', '/usr/sbin', '/sbin']
+export const SYSTEM_BIN_DIRS = [...LEAD_BIN_DIRS, ...TAIL_BIN_DIRS]
+
+// Joins PATH strings or folder lists into one PATH: absolute folders only,
+// each once, in the order first seen.
+export function mergePath(...parts) {
+  const seen = new Set()
+  for (const part of parts) {
+    const list = Array.isArray(part) ? part : String(part || '').split(':')
+    for (const raw of list) {
+      const dir = String(raw || '').trim()
+      if (dir && dir.startsWith('/') && !dir.includes('\n')) seen.add(dir.replace(/(.)\/+$/, '$1'))
+    }
+  }
+  return [...seen].join(':')
+}
+
+const isDir = (p) => { try { return statSync(p).isDirectory() } catch { return false } }
+
+// The usual folders that exist on this machine.
+export function knownBinDirs(home = os.homedir(), exists = isDir) {
+  return [...USER_BIN_DIRS.map(d => path.join(home, d)), ...SYSTEM_BIN_DIRS].filter(d => exists(d))
+}
+
+// herdr-projects' data folder, as it finds it: HERDR_PROJECTS_DATA_DIR, else
+// HERDR_PROJECTS_HOME/data, else ~/.herdr-projects/data.
+export function projectsDataDir(env = process.env, home = os.homedir()) {
+  return env.HERDR_PROJECTS_DATA_DIR || path.join(env.HERDR_PROJECTS_HOME || path.join(home, '.herdr-projects'), 'data')
+}
+
+// The PATH herdr-projects recorded from a login shell, '' when there is none.
+export function projectsEnvPath(env = process.env, home = os.homedir()) {
+  const file = path.join(projectsDataDir(env, home), 'env.json')
+  if (!existsSync(file)) return ''
+  try {
+    const p = JSON.parse(readFileSync(file, 'utf8'))?.PATH
+    return typeof p === 'string' ? p : ''
+  } catch { return '' }
+}
+
+// The PATH line of `env` output; what a shell prints before it is ignored.
+export function pathFromEnvOutput(text) {
+  const line = String(text || '').split('\n').find(l => l.startsWith('PATH='))
+  return line ? line.slice(5).trim() : ''
+}
+
+// The login shell's PATH ($SHELL -lc env), '' when it cannot be had. Never
+// interactive: no terminal, a few seconds at most.
+export function loginShellPath(env = process.env, run = spawnSync) {
+  const shell = env.SHELL && path.isAbsolute(env.SHELL) ? env.SHELL : '/bin/sh'
+  try {
+    const r = run(shell, ['-lc', 'env'], { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'], env })
+    return r.status === 0 ? pathFromEnvOutput(r.stdout) : ''
+  } catch { return '' }
+}
+
+// The PATH for the server and the commands it runs.
+// `first`: folders to put before everything (the runtime's own folder).
+// `login`: the login shell's PATH, when it was asked.
+export function userPath({ env = process.env, home = os.homedir(), first = [], login = '', exists = isDir } = {}) {
+  const lead = [...USER_BIN_DIRS.map(d => path.join(home, d)), ...LEAD_BIN_DIRS].filter(d => exists(d))
+  return mergePath(first, login, projectsEnvPath(env, home), lead, env.PATH || '', TAIL_BIN_DIRS.filter(d => exists(d)))
+}
+
+// The value of the first "PATH" key of a JSON file (env.json), its escapes
+// decoded as JSON.parse does (\" \\ \/ \b \f \n \r \t \uXXXX, surrogate
+// pairs as UTF-8), then an `x` so that the shell keeps a trailing newline.
+// Nothing when there is no such string, or when it is cut short, holds a NUL
+// or a bad escape. POSIX awk (BusyBox, mawk, BSD, gawk), run with LC_ALL=C so
+// that %c writes one byte. No single quote in it: the script quotes it so.
+export const JSON_PATH_AWK = String.raw`{ s = s $0 "\n" } `
+  + String.raw`function b(v) { return sprintf("%c", v) } `
+  + String.raw`function hex(t,   j, x, v) { if (length(t) != 4) return -1; v = 0; for (j = 1; j <= 4; j++) { x = index("0123456789abcdef", tolower(substr(t, j, 1))); if (!x) return -1; v = v * 16 + x - 1 } return v } `
+  + String.raw`END { if (!match(s, /"PATH"[ \t\r\n]*:[ \t\r\n]*"/)) exit; s = substr(s, RSTART + RLENGTH); n = length(s); o = ""; `
+  + String.raw`for (k = 1; k <= n; k++) { c = substr(s, k, 1); `
+  + String.raw`if (c == "\"") { printf "%sx", o; exit } `
+  + String.raw`if (c != "\\") { o = o c; continue } `
+  + String.raw`c = substr(s, ++k, 1); `
+  + String.raw`if (c == "\"" || c == "\\" || c == "/") o = o c; else if (c == "b") o = o "\b"; else if (c == "f") o = o "\f"; else if (c == "n") o = o "\n"; else if (c == "r") o = o "\r"; else if (c == "t") o = o "\t"; `
+  + String.raw`else if (c == "u") { v = hex(substr(s, k + 1, 4)); k += 4; `
+  + String.raw`if (v >= 55296 && v < 56320) { if (substr(s, k + 1, 2) != "\\u") exit; w = hex(substr(s, k + 3, 4)); if (w < 56320 || w >= 57344) exit; k += 6; v = 65536 + (v - 55296) * 1024 + w - 56320 } `
+  + String.raw`if (v <= 0 || (v >= 56320 && v < 57344)) exit; `
+  + String.raw`if (v < 128) o = o b(v); else if (v < 2048) o = o b(192 + int(v / 64)) b(128 + v % 64); `
+  + String.raw`else if (v < 65536) o = o b(224 + int(v / 4096)) b(128 + int(v / 64) % 64) b(128 + v % 64); `
+  + String.raw`else o = o b(240 + int(v / 262144)) b(128 + int(v / 4096) % 64) b(128 + int(v / 64) % 64) b(128 + v % 64) } `
+  + String.raw`else exit } }`
+
+// The same for a shell on another machine (SSH), by the rules of userPath:
+// the PATH herdr-projects recorded there, the usual user folders that exist
+// there, the shell's own PATH, then the system folders; each folder trimmed,
+// without a trailing slash, absolute, on one line and once. Fixed text, POSIX
+// sh and awk only; the recorded value is only split and assigned (no
+// globbing), never run.
+const ADD_SH = [
+  '  while :; do case "$d" in [$ws]*) d=${d#?} ;; *[$ws]) d=${d%?} ;; ?*/) d=${d%/} ;; *) break ;; esac; done',
+  '  case "$d" in /*) ;; *) continue ;; esac; case "$d" in *"$nl"*) continue ;; esac',
+  '  case ":$n:" in *":$d:"*) ;; *) n="${n:+$n:}$d" ;; esac',
+  'done',
+]
+const DIRS_SH = (dirs, home = false) => `for d in ${dirs.map(d => (home ? `"$HOME/${d}"` : d)).join(' ')}; do [ -d "$d" ] || continue`
+export const USER_PATH_SH = [
+  'f="${HERDR_PROJECTS_DATA_DIR:-${HERDR_PROJECTS_HOME:-$HOME/.herdr-projects}/data}/env.json"',
+  // awk where the system keeps it, even from a PATH without /usr/bin.
+  `p=""; [ -r "$f" ] && p=$(PATH="\${PATH:+$PATH:}/usr/bin:/bin" LC_ALL=C awk '${JSON_PATH_AWK}' "$f" 2>/dev/null); p=\${p%x}`,
+  "nl='\n'; ws=\" \t\r$nl\"; n=''; old_ifs=$IFS; IFS=:; set -f",
+  'for d in $p; do', ...ADD_SH,
+  DIRS_SH(USER_BIN_DIRS, true), ...ADD_SH,
+  DIRS_SH(LEAD_BIN_DIRS), ...ADD_SH,
+  'for d in $PATH; do', ...ADD_SH,
+  DIRS_SH(TAIL_BIN_DIRS), ...ADD_SH,
+  'set +f; IFS=$old_ifs; [ -n "$n" ] && PATH=$n; export PATH; ',
+].join('\n')

package/docs/README.md

@@ -0,0 +1,58 @@
+# Documentation
+
+**Upgrading to 2.0.0?** Read the [release notes](release-notes-2.0.0.md) for breaking changes and the 1.x migration checklist.
+
+Read only the page relevant to your task. Start with [Installation and updates](installation.md) for setup,
+[Security](security.md) for remote access, or [Development and tests](development.md) for repository changes.
+
+- [Overview and architecture](overview.md) — What wherdr does, why it exists and how it connects to Herdr. Includes the launch film and license.
+- [First launch](quick-start.md) — Install the native service and follow the setup guide. Includes the desktop, Board and phone screenshots.
+- [Home and agent list](home.md) — Find agents, create a session and filter machines or projects. Covers compact rows and state grouping.
+- [Conversation and replies](conversation.md) — Read transcripts, answer questions, attach files and manage drafts. Includes quoted replies and decision tables.
+- [Terminal](terminal.md) — Use the real terminal, copy text, open links and paste images. Explains take-over and size restoration.
+- [Files and changes](files.md) — Review Git changes and comment on lines or blocks. Compose a review for the agent.
+- [Computer, phone and iPad](devices.md) — Use split panes, keyboard shortcuts and touch controls. Describes device-specific layouts.
+- [Installation and updates](installation.md) — Requirements, native installer, agent PATH, updates and migration from Docker.
+- [Phone access and private networks](networks.md) — Set up Tailscale or another private network with HTTPS. Includes always-on servers and keep-awake.
+- [The wherdr command](command.md) — Install through npm or Homebrew and manage the native service from the command line.
+- [Herdr plugins](plugins.md) — Install and configure the wherdr plugin, its panel key and plugin actions.
+- [Install as an app](phone.md) — Add wherdr to your home screen on a phone or install it in a desktop browser.
+- [Settings and configuration](configuration.md) — Configure the service through environment variables and the app through shared and device-specific preferences.
+- [Machines and SSH](machines.md) — Register remote machines and use their agents through SSH. Includes sessions and connection troubleshooting.
+- [Claude and Codex quotas](quotas.md) — Show remaining usage and handle Codex updates, limits and restarts.
+- [Notifications](notifications.md) — Enable Web Push, relay Herdr notifications and configure Do not disturb.
+- [Board and coordinators](board.md) — Work with herdr-projects tasks, reviews, approvals and coordinators across machines.
+- [Security](security.md) — Understand remote-shell access, passkeys and network restrictions. Read this before enabling remote access.
+- [Development and tests](development.md) — Run from source and follow the contribution and agent test rules.
+- [Troubleshooting](troubleshooting.md) — Resolve startup, permissions, network, SSH and conversation problems.
+
+Also see [herdr-projects 1.x migration](herdr-projects-1x.md), [Releasing](RELEASING.md),
+[keyboard shortcut specification](product/keyboard-shortcuts.md) and [Contributing](../CONTRIBUTING.md).
+
+## Section reference
+
+- [Quick start](quick-start.md#quick-start)
+- [Why wherdr](overview.md#why-wherdr)
+- [Features](home.md#features)
+- [How it works](overview.md#how-it-works)
+- [Requirements](installation.md#requirements)
+- [Installation](installation.md#installation): [ask your AI agent](installation.md#ask-your-ai-agent) ·
+  [or run the installer yourself](installation.md#the-one-command) ·
+  [which setup?](installation.md#which-setup) ·
+  [always-on server + Tailscale](networks.md#recommended-always-on-server--tailscale) ·
+  [other private networks](networks.md#other-private-networks) ·
+  [as a Herdr plugin](plugins.md#install-as-a-herdr-plugin) ·
+  [the `wherdr` command (npm, Homebrew)](command.md#the-wherdr-command) ·
+  [from source](development.md#from-source) ·
+  [moving from Docker to the native service](migrate-from-1.x-docker.md)
+- [Updating](installation.md#updating)
+- [Install it as an app](phone.md#install-it-as-an-app)
+- [Configuration](configuration.md#configuration)
+- [Several machines (SSH)](machines.md#several-machines-ssh)
+- [Claude and Codex quotas](quotas.md#claude-and-codex-quotas)
+- [Notifications](notifications.md#notifications)
+- [Works great with herdr-projects](board.md#works-great-with-herdr-projects)
+- [Herdr plugins](plugins.md#herdr-plugins)
+- [Security](security.md#security)
+- [Troubleshooting](troubleshooting.md#troubleshooting)
+- [Contributing](development.md#contributing) · [License](overview.md#license)