k0-board 0.1.0

package/platform/linux/metrics.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import { runQuiet, which } from '../shared/run.js'
+import { parsePs } from '../shared/ps.js'
+
+const PS = () => which('ps', ['/bin/ps', '/usr/bin/ps'])
+
+export async function processes() {
+  // Same five fields in the same order as macOS, so one parser covers both. `args` is
+  // Linux's name for what BSD calls `command`.
+  return parsePs(await runQuiet(PS(), ['-eo', 'pid=,ppid=,rss=,time=,args='], { maxBuffer: 1 << 24 }))
+}
+
+const read = (file) => {
+  try {
+    return fs.readFileSync(file, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * /proc/meminfo, in kilobytes.
+ *
+ * "Used" is total minus MemAvailable, which is the kernel's own estimate of what a new
+ * process could get hold of without swapping — a far better answer than total minus free,
+ * which counts every cached file as memory somebody is short of.
+ *
+ * The macOS shape has fields Linux has no equivalent for. `wired` maps to the kernel's
+ * unreclaimable slab, `compressed` to zswap where it is on, and both are simply zero when
+ * the machine has nothing to put there.
+ */
+export function parseMeminfo(text) {
+  const kb = (label) => Number(new RegExp(`^${label}:\\s+(\\d+) kB`, 'm').exec(String(text ?? ''))?.[1] || 0) * 1024
+  const total = kb('MemTotal') || os.totalmem()
+  const available = kb('MemAvailable')
+  const cached = kb('Cached') + kb('Buffers')
+  const wired = kb('SUnreclaim')
+  const compressed = kb('Zswapped')
+  const used = available ? Math.max(0, total - available) : Math.max(0, total - kb('MemFree') - cached)
+  return { total, used, app: Math.max(0, used - wired - compressed), wired, compressed, cached }
+}
+
+export async function memory() {
+  return parseMeminfo(read('/proc/meminfo'))
+}
+
+export function parseSwapFromMeminfo(text) {
+  const kb = (label) => Number(new RegExp(`^${label}:\\s+(\\d+) kB`, 'm').exec(String(text ?? ''))?.[1] || 0) * 1024
+  const total = kb('SwapTotal')
+  return { total, used: Math.max(0, total - kb('SwapFree')) }
+}
+
+export async function swap() {
+  return parseSwapFromMeminfo(read('/proc/meminfo'))
+}
+
+/**
+ * Pressure Stall Information: the fraction of the last ten seconds in which at least one task
+ * was stalled waiting for memory. It is the closest thing Linux has to the macOS kernel's
+ * pressure verdict, and like it, it is a measurement rather than a guess — so the thresholds
+ * are the only part k0 chooses.
+ *
+ * Not every kernel is built with PSI, and cgroup-less containers do not expose it either;
+ * where the file is missing, `capabilities.pressure` says so and the board falls back to
+ * judging by how full memory is.
+ */
+export function parsePressure(text) {
+  const avg10 = Number(/some\s+avg10=([\d.]+)/.exec(String(text ?? ''))?.[1] || 0)
+  if (avg10 >= 20) return 4
+  if (avg10 >= 5) return 2
+  return 1
+}
+
+export async function pressureLevel() {
+  return parsePressure(read('/proc/pressure/memory'))
+}
+
+export const capabilities = () => ({
+  pressure: fs.existsSync('/proc/pressure/memory'),
+  swap: true,
+})
+
+export const notes = {
+  'metrics.pressure':
+    'This kernel does not expose /proc/pressure/memory, so k0 judges memory pressure by how ' +
+    'full memory is rather than by how much it is actually stalling.',
+}

package/platform/linux/power.js

@@ -0,0 +1,137 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { which } from '../shared/run.js'
+
+/**
+ * Keeping a Linux machine awake.
+ *
+ * The equivalent of `caffeinate` is `systemd-inhibit`, which holds a lock for as long as the
+ * command it runs is alive — so k0 runs a `sleep infinity` under it and kills that when the
+ * mode changes. Same shape as macOS, different lever.
+ *
+ * What is NOT here is the lid. On macOS a single system flag covers it; on Linux the lid is
+ * handled by logind, and changing it means editing /etc/systemd/logind.conf as root and
+ * reloading the daemon — a machine-wide setting that outlives k0 and that k0 has no business
+ * rewriting behind your back. So `lidSleep` is reported as unavailable, with a note that says
+ * what to change if you want it. Better a switch that is visibly off than one that lies.
+ */
+
+const SYSTEMD_INHIBIT = () => which('systemd-inhibit')
+const GNOME_INHIBIT = () => which('gnome-session-inhibit')
+
+const SUPPLY = '/sys/class/power_supply'
+
+let children = []
+let activeLevel = null
+
+/**
+ * Power source and charge, straight from sysfs. `AC`/`ADP*` entries report whether the mains
+ * are connected; `BAT*` entries report capacity. No battery at all means a desktop, and a
+ * desktop should never trip a battery threshold — hence `charge: null` rather than 100.
+ */
+export function readPowerSupply(dir = SUPPLY) {
+  let onAcPower = null
+  let charge = null
+  let entries = []
+  try {
+    entries = fs.readdirSync(dir)
+  } catch {
+    return { onAcPower: true, charge: null }
+  }
+  for (const name of entries) {
+    const read = (file) => {
+      try {
+        return fs.readFileSync(path.join(dir, name, file), 'utf8').trim()
+      } catch {
+        return ''
+      }
+    }
+    const type = read('type')
+    if (type === 'Mains') {
+      if (read('online') === '1') onAcPower = true
+      else if (onAcPower === null) onAcPower = false
+    } else if (type === 'Battery') {
+      const capacity = Number(read('capacity'))
+      if (Number.isFinite(capacity) && read('capacity') !== '') charge = capacity
+    }
+  }
+  return { onAcPower: onAcPower === null ? true : onAcPower, charge }
+}
+
+export async function state() {
+  return readPowerSupply()
+}
+
+function startInhibitor(bin, args) {
+  const child = spawn(bin, args, { stdio: 'ignore' })
+  child.on('error', () => {})
+  child.unref()
+  children.push(child)
+}
+
+export function inhibit(level) {
+  if (activeLevel === level) return
+  release()
+  if (!level) return
+  activeLevel = level
+
+  const systemd = SYSTEMD_INHIBIT()
+  if (systemd) {
+    startInhibitor(systemd, [
+      '--what=idle:sleep',
+      '--who=k0',
+      '--why=A Claude Code session is running',
+      '--mode=block',
+      'sleep',
+      'infinity',
+    ])
+  }
+  // Stopping the *screen* from going dark is a desktop-environment matter, not a logind one.
+  // gnome-session-inhibit covers GNOME, which is the common case; elsewhere the display may
+  // still blank, and `capabilities` says so.
+  if (level === 'display') {
+    const gnome = GNOME_INHIBIT()
+    if (gnome) startInhibitor(gnome, ['--inhibit', 'idle', '--reason', 'k0 driving mode', 'sleep', 'infinity'])
+  }
+}
+
+export function release() {
+  activeLevel = null
+  for (const child of children) {
+    try {
+      child.kill()
+    } catch {
+      /* already gone */
+    }
+  }
+  children = []
+}
+
+/** Not ours to change: see the note at the top of this file. */
+export async function setLidSleepBlocked() {}
+
+export async function lidSleepBlocked() {
+  return false
+}
+
+export function releaseSync() {
+  release()
+}
+
+export const capabilities = () => ({
+  keepAwake: !!SYSTEMD_INHIBIT(),
+  keepDisplayAwake: !!GNOME_INHIBIT(),
+  lidSleep: false,
+  battery: fs.existsSync(SUPPLY),
+})
+
+export const notes = {
+  'power.lidSleep':
+    'On Linux the lid is handled by logind. To keep working with the lid closed, set ' +
+    'HandleLidSwitch=ignore in /etc/systemd/logind.conf and reload logind. k0 will not ' +
+    'change a machine-wide setting for you.',
+  'power.keepDisplayAwake':
+    'Keeping the screen on needs a desktop-level inhibitor. k0 uses gnome-session-inhibit ' +
+    'where it exists; on other desktops the display may still blank.',
+}

package/platform/linux/service.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { run, runQuiet, which } from '../shared/run.js'
+
+/**
+ * Background services, systemd user-unit edition.
+ *
+ * User units, not system ones: k0 runs as you, needs your session's environment to find a
+ * display and a terminal, and has no business existing when you are not logged in. The one
+ * wrinkle is that a user unit normally stops when your last session ends — `loginctl
+ * enable-linger` is what keeps it alive on a headless box, and the installer only mentions
+ * it rather than turning it on, because it is a policy decision about your account.
+ */
+
+const SYSTEMCTL = () => which('systemctl')
+const UNIT_DIR = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user')
+
+export const SERVER_UNIT = 'k0.service'
+export const TRAY_UNIT = 'k0-tray.service'
+
+const unitPath = (unit) => path.join(UNIT_DIR, unit)
+
+function unitFile({ description, exec, port, logDir, workingDirectory }) {
+  return `[Unit]
+Description=${description}
+After=graphical-session.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+Environment=K0_PORT=${port}
+${workingDirectory ? `WorkingDirectory=${workingDirectory}\n` : ''}Restart=always
+RestartSec=2
+StandardOutput=append:${path.join(logDir, description.replace(/\s+/g, '-').toLowerCase())}.out.log
+StandardError=append:${path.join(logDir, description.replace(/\s+/g, '-').toLowerCase())}.err.log
+
+[Install]
+WantedBy=default.target
+`
+}
+
+const quote = (s) => (/[\s"']/.test(s) ? JSON.stringify(s) : s)
+
+export async function install({ node, entry, port, logDir, tray, appDir }) {
+  const systemctl = SYSTEMCTL()
+  if (!systemctl) throw new Error('k0 needs systemd to install a background service on Linux.')
+  fs.mkdirSync(UNIT_DIR, { recursive: true })
+  fs.mkdirSync(logDir, { recursive: true })
+
+  fs.writeFileSync(
+    unitPath(SERVER_UNIT),
+    unitFile({
+      description: 'k0 server',
+      exec: `${quote(node)} ${quote(entry)}`,
+      port,
+      logDir,
+      workingDirectory: appDir,
+    })
+  )
+  if (tray && fs.existsSync(tray)) {
+    const python = which('python3')
+    fs.writeFileSync(
+      unitPath(TRAY_UNIT),
+      unitFile({ description: 'k0 tray', exec: `${quote(python || 'python3')} ${quote(tray)}`, port, logDir })
+    )
+  }
+
+  await run(systemctl, ['--user', 'daemon-reload'])
+  await run(systemctl, ['--user', 'enable', '--now', SERVER_UNIT])
+  if (tray && fs.existsSync(unitPath(TRAY_UNIT))) {
+    await runQuiet(systemctl, ['--user', 'enable', '--now', TRAY_UNIT])
+  }
+}
+
+export async function uninstall() {
+  const systemctl = SYSTEMCTL()
+  for (const unit of [SERVER_UNIT, TRAY_UNIT]) {
+    if (systemctl) {
+      await runQuiet(systemctl, ['--user', 'disable', '--now', unit])
+    }
+    try {
+      fs.unlinkSync(unitPath(unit))
+    } catch {
+      /* never installed */
+    }
+  }
+  if (systemctl) await runQuiet(systemctl, ['--user', 'daemon-reload'])
+}
+
+export async function restart() {
+  await runQuiet(SYSTEMCTL(), ['--user', 'restart', SERVER_UNIT])
+}
+
+export async function status() {
+  const out = await runQuiet(SYSTEMCTL(), ['--user', 'is-active', SERVER_UNIT])
+  return { running: String(out).trim() === 'active' }
+}
+
+export const describe = () => [
+  { path: unitPath(SERVER_UNIT), what: 'a user service that starts k0 when you log in' },
+  { path: unitPath(TRAY_UNIT), what: 'a user service for the tray icon' },
+]
+
+export const capabilities = () => ({ autostart: !!SYSTEMCTL() })
+
+export const notes = {
+  'service.autostart':
+    'systemd was not found, so k0 cannot register itself to start at login. Run it by hand ' +
+    'with `k0-board start` or from your desktop’s own autostart configuration.',
+}

package/platform/linux/shell.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { run, runQuiet, runSyncQuiet, which } from '../shared/run.js'
+
+const XDG_OPEN = () => which('xdg-open')
+const DBUS_SEND = () => which('dbus-send')
+
+/**
+ * "Show me this file in the file manager" has a proper freedesktop answer — the FileManager1
+ * interface, which selects the file rather than just opening its folder — and a fallback for
+ * desktops that do not implement it, which is to open the containing directory and let you
+ * find it yourself.
+ */
+export async function revealInFileManager(abs) {
+  const dbus = DBUS_SEND()
+  if (dbus) {
+    const uri = `file://${encodeURI(abs)}`
+    const out = await runQuiet(dbus, [
+      '--session',
+      '--dest=org.freedesktop.FileManager1',
+      '--type=method_call',
+      '/org/freedesktop/FileManager1',
+      'org.freedesktop.FileManager1.ShowItems',
+      `array:string:${uri}`,
+      'string:',
+    ])
+    if (out !== '') return
+  }
+  const open = XDG_OPEN()
+  if (open) await runQuiet(open, [path.dirname(abs)])
+}
+
+export const openBrowser = (url) => run(XDG_OPEN(), [url], { timeout: 4000 })
+
+const CHROME_CANDIDATES = [
+  'google-chrome',
+  'google-chrome-stable',
+  'chromium',
+  'chromium-browser',
+  'brave-browser',
+  'microsoft-edge',
+]
+
+export function findChrome() {
+  for (const name of CHROME_CANDIDATES) {
+    const bin = which(name)
+    if (bin) return bin
+  }
+  for (const p of ['/snap/bin/chromium', '/usr/lib/chromium/chromium']) {
+    if (fs.existsSync(p)) return p
+  }
+  return null
+}
+
+/**
+ * Directories under $HOME that are never projects.
+ *
+ * The XDG names are the ones the desktop creates, and unlike macOS they can be localised —
+ * a French install has `Bureau` and `Téléchargements`. So the real list is read from
+ * user-dirs.dirs when it is there, with the English names as a floor for machines that have
+ * no desktop at all.
+ */
+export function homeSkipList() {
+  const skip = new Set(['Desktop', 'Documents', 'Downloads', 'Music', 'Pictures', 'Public', 'Templates', 'Videos', 'snap'])
+  const config = path.join(
+    process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'),
+    'user-dirs.dirs'
+  )
+  try {
+    for (const line of fs.readFileSync(config, 'utf8').split('\n')) {
+      const m = /^XDG_\w+_DIR="\$HOME\/(.+)"/.exec(line.trim())
+      if (m) skip.add(m[1].replace(/\/$/, ''))
+    }
+  } catch {
+    /* no desktop configuration: the defaults above are enough */
+  }
+  return skip
+}
+
+let claudeBin = null
+
+export function findClaude() {
+  if (claudeBin) return claudeBin
+  const candidates = [
+    path.join(os.homedir(), '.local/bin/claude'),
+    '/usr/local/bin/claude',
+    '/usr/bin/claude',
+  ]
+  for (const c of candidates) if (fs.existsSync(c)) return (claudeBin = c)
+  const shell = process.env.SHELL || '/bin/bash'
+  const fromShell = runSyncQuiet(shell, ['-lc', 'command -v claude']).trim()
+  claudeBin = fromShell || which('claude') || 'claude'
+  return claudeBin
+}
+
+export const capabilities = () => ({ revealInFileManager: !!XDG_OPEN() })

package/platform/linux/tray.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""k0's tray icon for Linux.
+
+The counterpart of menubar/K0MenuBar.swift, and deliberately the same shape: poll
+/api/status every couple of seconds, tint a small square with the colour of the most urgent
+session, and put the sessions that are waiting for you at the top of the menu so one click
+brings the right terminal back.
+
+Written in Python because it is the only language with a tray binding that is already
+installed on a normal desktop: GNOME, KDE and the rest ship python3 with PyGObject. Anything
+else would mean asking people to install a toolkit before they can see an icon. There are no
+third-party imports here — the PNG the icon is made of is written by hand with zlib, which is
+in the standard library, precisely so that this file never needs a pip install.
+
+If PyGObject or an AppIndicator implementation is missing, this exits quietly. The board and
+the server work perfectly without a tray icon; refusing to start would be worse than not
+having one.
+"""
+
+import json
+import os
+import struct
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+import zlib
+
+try:
+    import gi
+
+    gi.require_version("Gtk", "3.0")
+    try:
+        gi.require_version("AyatanaAppIndicator3", "0.1")
+        from gi.repository import AyatanaAppIndicator3 as AppIndicator
+    except (ValueError, ImportError):
+        gi.require_version("AppIndicator3", "0.1")
+        from gi.repository import AppIndicator3 as AppIndicator
+    from gi.repository import GLib, Gtk
+except (ImportError, ValueError) as err:  # pragma: no cover - depends on the desktop
+    print(f"k0: no tray support on this desktop ({err}); the board still works", file=sys.stderr)
+    raise SystemExit(0)
+
+
+PORT = os.environ.get("K0_PORT", "4319")
+BASE = f"http://127.0.0.1:{PORT}"
+POLL_SECONDS = 2
+
+CACHE = os.path.join(
+    os.environ.get("XDG_CACHE_HOME", os.path.expanduser("~/.cache")), "k0", "tray"
+)
+
+# The same colours and the same order of urgency as the board and the macOS menu bar icon.
+# ASK first because a question blocks everything behind it; COMPLETED never gets here.
+URGENCY = ["ASK", "PLANNED", "IDLE", "WORKING", "PLANNING"]
+COLOURS = {
+    "ASK": (0xE8, 0x6A, 0x33),
+    "PLANNED": (0x6C, 0x8E, 0xBF),
+    "IDLE": (0xE0, 0xC0, 0x4A),
+    "WORKING": (0x5B, 0xA8, 0x6A),
+    "PLANNING": (0x8E, 0x7C, 0xC3),
+    "quiet": (0x9A, 0x9A, 0x9A),
+    "down": (0xB0, 0x50, 0x50),
+}
+LABELS = {
+    "ASK": "Needs answer",
+    "PLANNED": "Needs approval",
+    "IDLE": "Your turn",
+    "WORKING": "Working",
+    "PLANNING": "Planning",
+}
+MODES = [("sleep", "Sleep"), ("away", "Away"), ("nerd", "Nerd"), ("driving", "Driving")]
+
+
+def png(rgb, size=22):
+    """A solid rounded square, as PNG bytes.
+
+    Hand-rolled so the tray needs nothing but the standard library. The corners are cut by
+    simply not drawing the four corner pixels, which at this size reads as rounded.
+    """
+    r, g, b = rgb
+    rows = bytearray()
+    for y in range(size):
+        rows.append(0)  # PNG filter type for this scanline: none
+        for x in range(size):
+            edge = (x < 2 or x >= size - 2) and (y < 2 or y >= size - 2)
+            rows += bytes((r, g, b, 0 if edge else 255))
+
+    def chunk(tag, data):
+        return (
+            struct.pack(">I", len(data))
+            + tag
+            + data
+            + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)
+        )
+
+    header = struct.pack(">IIBBBBB", size, size, 8, 6, 0, 0, 0)
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", header)
+        + chunk(b"IDAT", zlib.compress(bytes(rows), 9))
+        + chunk(b"IEND", b"")
+    )
+
+
+def icon_for(state):
+    """Write the icon for `state` once and hand back its path."""
+    os.makedirs(CACHE, exist_ok=True)
+    path = os.path.join(CACHE, f"{state}.png")
+    if not os.path.exists(path):
+        with open(path, "wb") as fh:
+            fh.write(png(COLOURS.get(state, COLOURS["quiet"])))
+    return path
+
+
+def api(path, payload=None):
+    """One request to the server. Returns None when the server is not answering."""
+    data = json.dumps(payload).encode() if payload is not None else None
+    request = urllib.request.Request(
+        BASE + path,
+        data=data,
+        headers={"Content-Type": "application/json", "Origin": BASE},
+        method="POST" if data else "GET",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=3) as response:
+            body = response.read()
+            return json.loads(body) if body else {}
+    except (urllib.error.URLError, OSError, ValueError):
+        return None
+
+
+def notify(title, body):
+    try:
+        subprocess.Popen(["notify-send", "-a", "k0", title, body])
+    except OSError:
+        pass  # no notification daemon: not worth complaining about
+
+
+class Tray:
+    def __init__(self):
+        self.indicator = AppIndicator.Indicator.new(
+            "k0", icon_for("quiet"), AppIndicator.IndicatorCategory.APPLICATION_STATUS
+        )
+        self.indicator.set_status(AppIndicator.IndicatorStatus.ACTIVE)
+        self.menu = Gtk.Menu()
+        self.indicator.set_menu(self.menu)
+        self.seen = set()
+        self.first_pass = True
+        self.mode = None
+        self.build_menu([], down=True)
+        GLib.timeout_add_seconds(POLL_SECONDS, self.poll)
+        self.poll()
+
+    # ── the loop ────────────────────────────────────────────────────────────
+    def poll(self):
+        status = api("/api/status")
+        if status is None:
+            self.indicator.set_icon_full(icon_for("down"), "k0: server not responding")
+            self.build_menu([], down=True)
+            return True
+
+        waiting = status.get("waiting") or []
+        urgent = status.get("urgent")
+        self.mode = status.get("mode")
+        self.indicator.set_icon_full(
+            icon_for(urgent or "quiet"),
+            LABELS.get(urgent, "k0 — nothing waiting for you"),
+        )
+        self.build_menu(waiting, down=False)
+        self.announce(waiting)
+        return True
+
+    def announce(self, waiting):
+        """Notify about cards that have just started waiting, not about every one every time."""
+        now = {(card["id"], card["status"]) for card in waiting}
+        if not self.first_pass:
+            for card in waiting:
+                if (card["id"], card["status"]) not in self.seen:
+                    notify(LABELS.get(card["status"], "k0"), card.get("title", ""))
+        self.seen = now
+        self.first_pass = False
+
+    # ── the menu ────────────────────────────────────────────────────────────
+    def build_menu(self, waiting, down):
+        for child in self.menu.get_children():
+            self.menu.remove(child)
+
+        if down:
+            self.add_item("Server not responding", None, enabled=False)
+        elif not waiting:
+            self.add_item("Nothing waiting for you", None, enabled=False)
+        else:
+            for card in waiting:
+                label = f"{LABELS.get(card['status'], card['status'])} — {card.get('title', '')}"
+                self.add_item(label, lambda _w, c=card: api(f"/api/card/{c['id']}/focus", {}))
+
+        self.menu.append(Gtk.SeparatorMenuItem())
+        for value, label in MODES:
+            item = Gtk.CheckMenuItem(label=label)
+            item.set_active(self.mode == value)
+            item.connect("activate", self.on_mode, value)
+            item.show()
+            self.menu.append(item)
+
+        self.menu.append(Gtk.SeparatorMenuItem())
+        self.add_item("Dashboard", lambda _w: subprocess.Popen(["xdg-open", BASE]))
+        self.add_item("Restart server", lambda _w: subprocess.Popen(["systemctl", "--user", "restart", "k0.service"]))
+        self.add_item("Quit", lambda _w: Gtk.main_quit())
+        self.menu.show_all()
+
+    def add_item(self, label, handler, enabled=True):
+        item = Gtk.MenuItem(label=label)
+        item.set_sensitive(enabled and handler is not None)
+        if handler:
+            item.connect("activate", handler)
+        item.show()
+        self.menu.append(item)
+
+    def on_mode(self, widget, value):
+        # A CheckMenuItem fires `activate` when it is rebuilt too, which would post the mode
+        # back to the server in an endless loop. Only a real change is worth a request.
+        if widget.get_active() and self.mode != value:
+            api("/api/mode", {"mode": value})
+
+
+if __name__ == "__main__":
+    Tray()
+    Gtk.main()

package/platform/shared/command.js

@@ -0,0 +1,26 @@
+/**
+ * Turning "run this program, in this directory, with these arguments" into one line a shell
+ * will accept.
+ *
+ * It has to be one line because that is all a terminal can be handed: there is no argv on the
+ * far side, only text typed into a shell. Which makes quoting the whole of the problem — a
+ * project directory called `My Projects` or `it's-mine` has to survive the trip intact, and
+ * a prompt passed as an argument can contain anything at all.
+ */
+
+/** POSIX single quotes: everything is literal inside them, and a quote ends and reopens them. */
+export const posixQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`
+
+export const posixCommand = ({ cwd, bin, args = [] }) =>
+  ['cd', posixQuote(cwd), '&&', posixQuote(bin), ...args.map(posixQuote)].join(' ')
+
+/** PowerShell single quotes: same idea, but a quote is escaped by doubling it. */
+export const powershellQuote = (s) => `'${String(s).replace(/'/g, "''")}'`
+
+export const powershellCommand = ({ cwd, bin, args = [] }) =>
+  [
+    `Set-Location ${powershellQuote(cwd)};`,
+    '&',
+    powershellQuote(bin),
+    ...args.map(powershellQuote),
+  ].join(' ')