k0-board 0.1.2 → 0.3.0

package/platform/darwin/index.js

@@ -1,6 +1,7 @@
 import * as terminal from './terminal.js'
 import * as power from './power.js'
 import * as metrics from './metrics.js'
+import * as servers from './servers.js'
 import * as shell from './shell.js'
 import * as service from './service.js'
 import { extras } from './extras.js'
@@ -13,12 +14,26 @@ export const capabilities = {
   terminal: terminal.capabilities,
   power: power.capabilities,
   metrics: metrics.capabilities,
+  servers: servers.capabilities(),
   service: service.capabilities,
   tray: true,
   revealInFileManager: true,
 }
 
-/** Nothing is missing here, so there is nothing to explain. */
-export const notes = {}
+/**
+ * Nothing is missing here, so there is nothing to explain — with one exception that is not
+ * about macOS but about a particular Mac: lsof ships with the system, and if it has been taken
+ * away k0 says what it can no longer see rather than showing every dev server as off.
+ */
+export const notes = {
+  ...(capabilities.servers.ports
+    ? {}
+    : {
+        'servers.ports':
+          'lsof was not found on this Mac. It ships with macOS, so something has removed or ' +
+          'blocked it — without it k0 cannot see which port a dev server is listening on, or ' +
+          'recognise one you started yourself.',
+      }),
+}
 
-export { terminal, power, metrics, shell, service, extras }
+export { terminal, power, metrics, servers, shell, service, extras }

package/platform/darwin/servers.js

@@ -0,0 +1,16 @@
+import { lsofListeners, lsofCwds, LSOF, stop, shell } from '../shared/servers.js'
+
+/**
+ * Dev servers on macOS. Everything comes out of one `lsof`, which ships with the system, so
+ * there is nothing to install and nothing that can be missing — but the capability is still
+ * probed rather than declared, because a machine with a locked-down /usr/sbin is a machine
+ * where the globe has to say so instead of showing every server as off.
+ */
+export const capabilities = () => {
+  const has = !!LSOF()
+  return { run: true, ports: has, adopt: has }
+}
+
+export const listeners = lsofListeners
+export const cwds = lsofCwds
+export { stop, shell }

package/platform/index.js

@@ -56,6 +56,13 @@ const unsupported = {
     swap: async () => ({ total: 0, used: 0 }),
     pressureLevel: async () => 1,
   },
+  servers: {
+    capabilities: () => ({ run: false, ports: false, adopt: false }),
+    listeners: async () => new Map(),
+    cwds: async () => new Map(),
+    shell: (command) => ({ file: process.env.SHELL || '/bin/sh', args: ['-lc', command] }),
+    stop: async () => false,
+  },
   shell: {
     revealInFileManager: async () => {},
     openBrowser: async () => {},
@@ -78,7 +85,8 @@ const unsupported = {
 const platform = load ? { ...unsupported, ...(await load()) } : unsupported
 
 export default platform
-export const { name, capabilities, notes, terminal, power, metrics, shell, service, extras } = platform
+export const { name, capabilities, notes, terminal, power, metrics, servers, shell, service, extras } =
+  platform
 
 /**
  * Is this capability available here? Takes a dotted path, so callers read as a question:

package/platform/linux/index.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import * as tmux from '../shared/tmux.js'
 import * as power from './power.js'
 import * as metrics from './metrics.js'
+import * as servers from './servers.js'
 import * as shell from './shell.js'
 import * as service from './service.js'
 import { NO_CAPABILITIES } from '../contract.js'
@@ -19,6 +20,7 @@ export const capabilities = {
   terminal: tmux.capabilities(),
   power: power.capabilities(),
   metrics: metrics.capabilities(),
+  servers: servers.capabilities(),
   service: service.capabilities(),
   tray: !!which('python3'),
   revealInFileManager: shell.capabilities().revealInFileManager,
@@ -52,9 +54,24 @@ export const notes = {
   ...(capabilities.tray
     ? {}
     : { tray: 'python3 with PyGObject is needed for a tray icon. The board works without it.' }),
+  ...(capabilities.servers.ports
+    ? {}
+    : {
+        'servers.ports':
+          'Neither ss nor lsof was found, so k0 cannot see which port a dev server is listening ' +
+          'on. Install iproute2 (for ss) and the globe will know where to send you.',
+      }),
+  ...(capabilities.servers.adopt
+    ? {}
+    : {
+        'servers.adopt':
+          'This system has no /proc, so k0 cannot tell which repository a dev server you ' +
+          'started yourself belongs to. The globe switches on and off the servers k0 started, ' +
+          'and says nothing about the others rather than showing them as off.',
+      }),
 }
 
-export { power, metrics, shell, service }
+export { power, metrics, servers, shell, service }
 
 /** Nothing on Linux reaches outside k0's own files, so there is nothing to consent to. */
 export const extras = []

package/platform/linux/servers.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs'
+import { lsofListeners, ssListeners, LSOF, stop, shell } from '../shared/servers.js'
+import { which } from '../shared/run.js'
+
+/**
+ * Dev servers on Linux.
+ *
+ * Two differences from macOS. Listening sockets can come from `ss` as well as from `lsof`, and
+ * `ss` is the one a minimal system is likelier to have — it arrives with iproute2, where lsof
+ * arrives with nothing. And the working directory of a process is a symlink in /proc, which is
+ * both cheaper than lsof and always there, so adoption works even where neither tool is.
+ */
+const hasSs = () => !!which('ss', ['/usr/sbin/ss', '/usr/bin/ss', '/sbin/ss'])
+
+export const capabilities = () => ({
+  run: true,
+  ports: !!LSOF() || hasSs(),
+  // /proc is what makes this true, and it is what a container without it makes false.
+  adopt: fs.existsSync('/proc/self/cwd'),
+})
+
+/** lsof first when it is there — it answers both questions in the same shape as macOS. */
+export async function listeners() {
+  if (LSOF()) return lsofListeners()
+  return ssListeners()
+}
+
+/** One readlink each. A process that ends mid-loop is skipped, not an error. */
+export async function cwds(pids) {
+  const out = new Map()
+  for (const pid of pids) {
+    try {
+      out.set(pid, fs.readlinkSync(`/proc/${pid}/cwd`))
+    } catch {
+      /* gone, or not ours to look at */
+    }
+  }
+  return out
+}
+
+export { stop, shell }

package/platform/shared/listeners.js

@@ -0,0 +1,121 @@
+/**
+ * Who is listening on which port, and where a process is working from.
+ *
+ * These are the two questions behind the globe in the column headings: a dev server is up if
+ * something it started holds a TCP port open, and a dev server somebody started by hand belongs
+ * to a repository if it is working from inside it.
+ *
+ * macOS and Linux answer both with the same `lsof`, in its field format, so one parser serves
+ * both — the same arrangement `ps.js` already has for the process table. Windows answers the
+ * first with PowerShell and cannot answer the second at all, which is exactly why the shape and
+ * not the command is what lives here.
+ *
+ * Nothing in this file opens a socket. It asks the operating system who is already holding one,
+ * which is both stronger evidence than a reply to a request and the only reading of "is it up"
+ * that k0 is allowed to take — see the rule about network requests in CLAUDE.md.
+ */
+
+/**
+ * lsof's field format is a stream of sets: `p<pid>` opens a process and every line after it
+ * belongs to that process until the next `p`. lsof emits `f<fd>` lines whether they were asked
+ * for or not, so anything that is not the field being read is stepped over rather than parsed.
+ *
+ * @param {string} out
+ * @param {string} field  the one-letter field to collect, `n` for both callers here
+ * @param {(pid: number, value: string) => void} take
+ */
+function eachField(out, field, take) {
+  let pid = null
+  for (const line of String(out ?? '').split('\n')) {
+    if (line[0] === 'p') {
+      const n = Number(line.slice(1))
+      pid = Number.isInteger(n) && n > 0 ? n : null
+    } else if (line[0] === field && pid !== null) {
+      take(pid, line.slice(1))
+    }
+  }
+}
+
+/**
+ * The port out of an address as lsof writes it: `*:4321`, `127.0.0.1:4321`, `[::1]:4321`.
+ * The last colon is the separator in all three, which is what makes IPv6 harmless here.
+ */
+export function portOf(address) {
+  const at = String(address ?? '').lastIndexOf(':')
+  if (at < 0) return null
+  const tail = address.slice(at + 1)
+  if (!/^\d+$/.test(tail)) return null
+  const port = Number(tail)
+  return port > 0 && port < 65536 ? port : null
+}
+
+/**
+ * `lsof -nP -iTCP -sTCP:LISTEN -F pn` as a map of pid to the ports it holds open.
+ * A process listening on both IPv4 and IPv6 shows the same port twice; the set folds them.
+ */
+export function parseListeners(out) {
+  const ports = new Map()
+  eachField(out, 'n', (pid, address) => {
+    const port = portOf(address)
+    if (port === null) return
+    if (!ports.has(pid)) ports.set(pid, new Set())
+    ports.get(pid).add(port)
+  })
+  return ports
+}
+
+/**
+ * `lsof -a -d cwd -p 1,2,3 -F n` as a map of pid to the directory it is working from.
+ * A process has exactly one, so the first answer for a pid is the answer.
+ */
+export function parseCwds(out) {
+  const cwds = new Map()
+  eachField(out, 'n', (pid, dir) => {
+    if (!cwds.has(pid) && dir) cwds.set(pid, dir)
+  })
+  return cwds
+}
+
+/**
+ * `ss -H -ltnp`, the answer on a Linux that has no lsof — which is most minimal ones, since
+ * `ss` comes with iproute2 and lsof does not come with anything.
+ *
+ *     LISTEN 0 511 *:4321 *:* users:(("node",pid=1234,fd=20))
+ *
+ * The listening address is the fourth column and the pids are in the tail, one process per
+ * `pid=`: a socket can be shared by a parent and its children, and then all of them own it.
+ */
+export function parseSs(out) {
+  const ports = new Map()
+  for (const line of String(out ?? '').split('\n')) {
+    const cols = line.trim().split(/\s+/)
+    if (cols.length < 4) continue
+    const port = portOf(cols[3])
+    if (port === null) continue
+    for (const m of line.matchAll(/pid=(\d+)/g)) {
+      const pid = Number(m[1])
+      if (!pid) continue
+      if (!ports.has(pid)) ports.set(pid, new Set())
+      ports.get(pid).add(port)
+    }
+  }
+  return ports
+}
+
+/**
+ * `Get-NetTCPConnection -State Listen` piped through `ConvertTo-Csv`, which is how Windows
+ * answers the same question. Two columns, `LocalPort` and `OwningProcess`, in that order.
+ */
+export function parseNetTcp(out) {
+  const ports = new Map()
+  for (const line of String(out ?? '').split('\n')) {
+    const m = /^"?(\d+)"?\s*,\s*"?(\d+)"?\s*$/.exec(line.trim())
+    if (!m) continue
+    const port = Number(m[1])
+    const pid = Number(m[2])
+    if (!pid || port <= 0 || port >= 65536) continue
+    if (!ports.has(pid)) ports.set(pid, new Set())
+    ports.get(pid).add(port)
+  }
+  return ports
+}

package/platform/shared/servers.js

@@ -0,0 +1,111 @@
+/**
+ * Dev servers, the parts that are the same on macOS and Linux.
+ *
+ * Both have `lsof`, both have a `ps` that knows about process groups, and both signal a whole
+ * group by signalling a negative pid. What they do not share is how to ask where a process is
+ * working from — macOS goes through lsof, Linux reads a symlink — so that one stays with each
+ * adapter and only the rest is here.
+ */
+
+import { runQuiet, which, alive } from './run.js'
+import { parseListeners, parseCwds, parseSs } from './listeners.js'
+
+export const LSOF = () => which('lsof', ['/usr/sbin/lsof', '/usr/bin/lsof'])
+const SS = () => which('ss', ['/usr/sbin/ss', '/usr/bin/ss', '/sbin/ss'])
+const PS = () => which('ps', ['/bin/ps', '/usr/bin/ps'])
+
+// Asking the whole machine who is listening is not free — measured in the hundreds of
+// milliseconds on a busy laptop — so the caller is expected to do it rarely. See the sampling
+// discipline in server/servers.js, which is the one machine.js already lives by.
+const TIMEOUT = 8000
+
+/**
+ * How to run a project's own command. A LOGIN shell, so that a version manager's PATH and the
+ * project's own `.nvmrc` are in force — under a launch agent the inherited PATH is barely more
+ * than /usr/bin:/bin, and `npm` would simply not be found. It is the same reason `findClaude`
+ * ends up asking a shell.
+ */
+export const shell = (command) => ({
+  file: process.env.SHELL || '/bin/sh',
+  args: ['-lc', command],
+})
+
+/** Everything holding a TCP port open, from lsof. */
+export async function lsofListeners() {
+  const bin = LSOF()
+  if (!bin) return new Map()
+  return parseListeners(await runQuiet(bin, ['-nP', '-iTCP', '-sTCP:LISTEN', '-F', 'pn'], { timeout: TIMEOUT }))
+}
+
+/** The same, from iproute2 — which a minimal Linux has when it has no lsof. */
+export async function ssListeners() {
+  const bin = SS()
+  if (!bin) return new Map()
+  return parseSs(await runQuiet(bin, ['-H', '-l', '-t', '-n', '-p'], { timeout: TIMEOUT }))
+}
+
+/** Where each of these processes is working from, from lsof. */
+export async function lsofCwds(pids) {
+  const bin = LSOF()
+  if (!bin || !pids.length) return new Map()
+  return parseCwds(await runQuiet(bin, ['-a', '-d', 'cwd', '-p', pids.join(','), '-F', 'n'], { timeout: TIMEOUT }))
+}
+
+/**
+ * The process group a pid belongs to. Empty when the process is already gone, which is not an
+ * error: it is the answer.
+ */
+export async function pgidOf(pid) {
+  const bin = PS()
+  if (!bin || !pid) return null
+  const pgid = Number(String(await runQuiet(bin, ['-o', 'pgid=', '-p', String(pid)])).trim())
+  return Number.isInteger(pgid) && pgid > 1 ? pgid : null
+}
+
+/**
+ * Stop a dev server and everything it started.
+ *
+ * Signalling the group rather than the process is the whole point. `npm run dev` is a shell
+ * that spawns `vite`, and a SIGTERM to npm alone leaves vite holding the port — which is
+ * precisely what the old per-repo skill was working around with `pkill -f "astro dev"`.
+ *
+ * But the group is only signalled when `root` is the group's LEADER, and that restraint is not
+ * pedantry. A server k0 started is `detached`, so it leads its own group and the fast path is
+ * always taken. A server somebody started by hand is a different matter: under job control its
+ * group leader is the npm it was typed as, but in a script, or under a shell with job control
+ * off, the group can be the SHELL's — and signalling that would close the user's terminal to
+ * stop a dev server. So when `root` does not lead the group, the pids are signalled one by one
+ * instead, children before parents, which is slower and cannot take anything with it that the
+ * caller did not name.
+ *
+ * @param {number} root  the topmost process of the server
+ * @param {number[]} pids  every process under it, `root` included — see `subtree` in machine.js
+ * @param {'SIGTERM'|'SIGKILL'} signal
+ */
+export async function stop(root, pids, signal = 'SIGTERM') {
+  if (!root) return false
+  const pgid = await pgidOf(root)
+  if (pgid === root) {
+    try {
+      process.kill(-pgid, signal)
+      return true
+    } catch {
+      // Already gone between the question and the signal. Fall through: the loop below is
+      // harmless on a dead process and is what answers honestly.
+    }
+  }
+  let touched = false
+  // Youngest first — a higher pid is a later process, which in a tree grown in one go is the
+  // child. It is a tendency and not a guarantee, but the order only decides who sees its parent
+  // disappear first, and SIGTERM reaches all of them either way.
+  for (const pid of [...new Set([...pids, root])].sort((a, b) => b - a)) {
+    if (!alive(pid)) continue
+    try {
+      process.kill(pid, signal)
+      touched = true
+    } catch {
+      /* it went on its own between the check and the signal */
+    }
+  }
+  return touched
+}

package/platform/win32/index.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import * as terminal from './terminal.js'
 import * as power from './power.js'
 import * as metrics from './metrics.js'
+import * as servers from './servers.js'
 import * as shell from './shell.js'
 import * as service from './service.js'
 import { NO_CAPABILITIES } from '../contract.js'
@@ -19,6 +20,7 @@ export const capabilities = {
   terminal: terminal.capabilities(),
   power: power.capabilities(),
   metrics: metrics.capabilities(),
+  servers: servers.capabilities(),
   service: service.capabilities(),
   tray: hasPowerShell(),
   revealInFileManager: true,
@@ -45,9 +47,21 @@ export const notes = {
           'PowerShell was not found. k0 needs it to open, place and raise terminal windows on ' +
           'Windows.',
       }),
+  'servers.adopt':
+    'Windows does not let one process read another’s working directory, so k0 cannot tell ' +
+    'which repository a dev server you started yourself belongs to. The globe switches on and ' +
+    'off the servers k0 started, and says nothing about the others rather than showing them ' +
+    'as off.',
+  ...(hasPowerShell()
+    ? {}
+    : {
+        'servers.ports':
+          'PowerShell was not found, so k0 cannot see which port a dev server is listening on. ' +
+          'It can still start and stop one, but the globe cannot open it for you.',
+      }),
 }
 
-export { terminal, power, metrics, shell, service }
+export { terminal, power, metrics, servers, shell, service }
 
 /** Nothing on Windows reaches outside k0's own files, so there is nothing to consent to. */
 export const extras = []

package/platform/win32/servers.js

@@ -0,0 +1,73 @@
+import { psJson, psQuiet, POWERSHELL } from './powershell.js'
+import { which, runQuiet } from '../shared/run.js'
+
+/**
+ * Dev servers on Windows.
+ *
+ * Listening sockets come from `Get-NetTCPConnection`, which has carried an owning process id
+ * since Windows 8 and needs nothing installed. Stopping goes through `taskkill /T`, which walks
+ * the tree itself — Windows has no process groups to signal, and killing `npm` alone would
+ * leave the server holding the port exactly as it does everywhere else.
+ *
+ * What Windows will not answer is where another process is working from. There is no /proc and
+ * no lsof; getting it means opening the process and reading its PEB, which is a native module,
+ * and k0 has no dependencies. So adoption is off here and the interface SAYS so — a server
+ * somebody started by hand is reported as unknown rather than drawn as off. See the note in
+ * index.js, which is the sentence the board shows.
+ */
+const hasPowerShell = () => !!POWERSHELL()
+
+export const capabilities = () => ({
+  run: true,
+  ports: hasPowerShell(),
+  adopt: false,
+})
+
+export async function listeners() {
+  if (!hasPowerShell()) return new Map()
+  const rows = await psJson(
+    '@(Get-NetTCPConnection -State Listen | Select-Object LocalPort, OwningProcess)',
+    []
+  )
+  const ports = new Map()
+  for (const row of Array.isArray(rows) ? rows : [rows].filter(Boolean)) {
+    const pid = Number(row.OwningProcess)
+    const port = Number(row.LocalPort)
+    if (!pid || port <= 0 || port >= 65536) continue
+    if (!ports.has(pid)) ports.set(pid, new Set())
+    ports.get(pid).add(port)
+  }
+  return ports
+}
+
+/** Windows cannot say. An empty map is the honest answer, and `capabilities.adopt` explains it. */
+export async function cwds() {
+  return new Map()
+}
+
+/**
+ * `/T` takes the children with it and `/F` does not ask twice. There is no gentle signal on
+ * Windows worth sending first: a console application gets CTRL_BREAK or nothing, and nothing
+ * is what a detached one gets.
+ */
+export async function stop(root) {
+  if (!root) return false
+  const taskkill = which('taskkill', ['C:\\Windows\\System32\\taskkill.exe'])
+  if (taskkill) {
+    await runQuiet(taskkill, ['/PID', String(root), '/T', '/F'], { timeout: 8000 })
+    return true
+  }
+  if (!hasPowerShell()) return false
+  await psQuiet(`Stop-Process -Id ${Number(root)} -Force -ErrorAction SilentlyContinue`)
+  return true
+}
+
+/**
+ * Windows has no login shell whose PATH is worth inheriting, and `npm` is a `.cmd` that only
+ * the command processor knows how to run. `/d` skips whatever AutoRun command the registry
+ * would otherwise inject ahead of it.
+ */
+export const shell = (command) => ({
+  file: process.env.COMSPEC || 'cmd.exe',
+  args: ['/d', '/s', '/c', command],
+})