k0-board 0.1.0

package/server/launcher.js

@@ -0,0 +1,121 @@
+import { readLiveSessions } from './watcher.js'
+import { isDriving } from './mode.js'
+import { titleCase } from '../web/title.js'
+import { terminal, shell, capabilities } from '../platform/index.js'
+
+/**
+ * "fix now 2h" -> "Fix-Now-2h", which is the name you will see on the session.
+ * Same rule as the title field on the dashboard: the session's name is exactly what you saw
+ * yourself typing.
+ */
+export function sessionName(title) {
+  return titleCase(title).replace(/-+$/, '') || 'Untitled'
+}
+
+export const findClaude = () => shell.findClaude()
+
+/** In driving mode the terminal has to be readable from across the room. */
+const DRIVING_FONT_SIZE = 22
+
+/** How big the text has to be right now: it depends only on the mode in force. */
+const fontSize = () => (isDriving() ? Promise.resolve(DRIVING_FONT_SIZE) : terminal.defaultFontSize())
+
+export async function setTerminalFont(handles) {
+  return terminal.setFont(handles, await fontSize())
+}
+
+export const relayoutWindows = (handles) => terminal.relayout(handles)
+export const setWindowTitle = (handle, title) => terminal.setTitle(handle, title)
+export const focusWindow = (handle) => terminal.focus(handle)
+export const closeTerminal = ({ winId, pid }) => terminal.close({ handle: winId, pid })
+
+/** Waits for Claude to really be up: the session shows up in ~/.claude/sessions. */
+async function waitForSession(sessionId, timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (readLiveSessions().has(sessionId)) return true
+    await new Promise((r) => setTimeout(r, 300))
+  }
+  return false
+}
+
+/**
+ * The session file appears before the interface is ready to receive: writing at that moment
+ * loses the first characters and swallows the Enter. So we wait until the input box is
+ * actually visible in the window.
+ *
+ * Where the platform cannot read a terminal's screen — Windows — there is nothing to look at,
+ * and the only honest thing left is to wait a fixed moment. It is a guess, and the interface
+ * says so: `capabilities.terminal.readScreen` is false there, and the board explains what
+ * that costs.
+ */
+async function waitForPrompt(handle, timeoutMs = 15000) {
+  if (!capabilities.terminal.readScreen) {
+    await new Promise((r) => setTimeout(r, 3500))
+    return false
+  }
+  if (!handle) return false
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const screen = await terminal.readScreen(handle)
+    if (screen === null) return false // window gone
+    if (screen.includes('❯')) {
+      await new Promise((r) => setTimeout(r, 400)) // a moment for the first paint
+      return true
+    }
+    await new Promise((r) => setTimeout(r, 300))
+  }
+  return false
+}
+
+/**
+ * Starts (or resumes) a card's session.
+ * mode: 'start' assigns a new session id, 'resume' reopens the existing one.
+ */
+export async function launch({ card, sessionId, mode = 'start' }) {
+  const name = sessionName(card.title)
+  const bin = findClaude()
+  const resume = mode === 'resume'
+  const args = []
+  if (resume) {
+    // Resuming forces nothing: that session already had a mode, and it is not our place to
+    // change it.
+    args.push('--dangerously-skip-permissions', '--resume', sessionId)
+  } else {
+    // A new session is born in plan mode: that is how work happens here, and turning it on by
+    // hand at every start was the one thing standing between you and beginning.
+    //
+    // The permissions flag has to change here, and it is not a preference: it is provable that
+    // `--dangerously-skip-permissions` **switches off** plan mode — whatever order you write
+    // them in, the session starts in `bypassPermissions` and there is no sign of a plan. The
+    // two flags do not error together, and that is the trap: it looks like it works.
+    // `--allow-dangerously-skip-permissions` instead keeps "stop asking me" within reach of
+    // shift+tab without imposing it from the start, and it is the only way to really begin
+    // inside a plan. The price is that once the plan is approved it asks for confirmations.
+    args.push('--allow-dangerously-skip-permissions', '--permission-mode', 'plan', '--session-id', sessionId)
+  }
+  args.push('-n', name)
+  // With "send it for me" the prompt goes straight to the CLI and starts without touching
+  // anything.
+  const autoSend = mode === 'start' && card.auto_send && card.prompt?.trim()
+  if (autoSend) args.push(card.prompt.trim())
+
+  const command = terminal.buildCommand({ cwd: card.project_path, bin, args })
+  const winId = await terminal.open({ command, title: name, fontSize: await fontSize() })
+  const up = await waitForSession(sessionId)
+
+  if (autoSend) return { name, up, winId, pasted: true, autoSent: true }
+  if (!up || !card.prompt?.trim()) return { name, up, winId, pasted: false }
+
+  await waitForPrompt(winId)
+
+  if (capabilities.terminal.pasteWithoutSending) {
+    const res = await terminal.paste(card.prompt.trim(), winId)
+    if (res.pasted) return { name, up, winId, ...res }
+  }
+
+  // Pasting is unavailable or was refused — on macOS that means no Accessibility permission.
+  // We type it instead, which sends it.
+  const fallback = await terminal.type(card.prompt.trim(), winId)
+  return { name, up, winId, pasted: false, autoSent: fallback.written, ...fallback }
+}

package/server/machine.js

@@ -0,0 +1,213 @@
+import os from 'node:os'
+import { metrics } from '../platform/index.js'
+
+export { parsePs, cpuSeconds } from '../platform/shared/ps.js'
+
+// ── What all of this costs ────────────────────────────────────────────────────
+// The only place that looks at the machine's processes and memory. It answers two questions:
+// is the computer struggling, and who is making it struggle.
+//
+// The honest number for "what does this session cost" is not the `claude` process: it is its
+// whole subtree. A 200 MB claude can have an MCP server under it with Chrome behind that, and
+// a 200 MB `tsc` started from a commit hook. That is where the memory goes, and it is what no
+// other tool can attribute to the right card — Activity Monitor has never heard of cards.
+//
+// Summing the resident memory of a subtree counts shared memory twice between parent and
+// children, so the total is a little generous. It is the usual approximation, and it is the
+// right one for the question that matters here: which one do I close to feel better.
+
+const TTL = 3000 // how often the sample is retaken, while somebody is watching
+const ATTENTION = 15000 // how long a glance counts for before it goes quiet again
+const CORES = os.cpus().length
+
+/**
+ * Reading the process table costs little on a calm machine and a lot on a struggling one —
+ * measured: 30 ms to 360 ms — and struggling is exactly when you look at it. So it does not
+ * sit on the one-second loop, and it stops by itself as soon as nobody is looking.
+ */
+let watching = 0
+export function touch() {
+  watching = Date.now()
+  // On the first glance there is nothing to say yet: read straight away rather than leave the
+  // bar empty for the three seconds until the next round.
+  if (!snap) cycle()
+}
+
+let snap = null // { at, procs, kids, share, cpu, mem, swap, pressure }
+let prev = null // { at, cpu: Map<pid, seconds> } — the previous sample, for the differences
+let running = false
+
+/** Who descends from whom: the map needed to walk the subtrees. */
+export function childrenOf(procs) {
+  const kids = new Map()
+  for (const [pid, p] of procs) {
+    if (p.ppid === pid) continue // does not happen, but a loop here would spin forever
+    if (!kids.has(p.ppid)) kids.set(p.ppid, [])
+    kids.get(p.ppid).push(pid)
+  }
+  return kids
+}
+
+/** Every pid from `root` down, itself included. With the guard against cycles. */
+export function subtree(kids, root, seen = new Set()) {
+  if (seen.has(root)) return seen
+  seen.add(root)
+  for (const k of kids.get(root) ?? []) subtree(kids, k, seen)
+  return seen
+}
+
+/**
+ * The verdict is not ours to invent: on macOS and Linux the kernel publishes its own
+ * judgement — 1 normal, 2 warning, 4 critical. One rule is added to it, memory nearly gone,
+ * because that is the moment before the kernel notices. Swap deliberately does NOT enter the
+ * verdict: on macOS the swap file grows by itself, so "how full is it" does not mean much.
+ * How much is in use is read anyway and shown on hover: it is the number that explains the
+ * stutters.
+ *
+ * Where the kernel publishes nothing — Windows — the level is always 1 and the memory rule is
+ * the whole verdict.
+ */
+export function verdict(level, mem) {
+  if (level >= 4) return 'bad'
+  if (level >= 2 || (mem.total > 0 && mem.used / mem.total >= 0.9)) return 'warn'
+  return 'ok'
+}
+
+// ── The round ─────────────────────────────────────────────────────────────────
+async function cycle() {
+  if (running || Date.now() - watching > ATTENTION) return
+  running = true
+  try {
+    const [procs, mem, sw, level] = await Promise.all([
+      metrics.processes(),
+      metrics.memory(),
+      metrics.swap(),
+      metrics.pressureLevel(),
+    ])
+    const at = Date.now()
+
+    // The CPU right now, not the average since the process was born: that second one is what
+    // `ps` reports as `%cpu`, and on an old process it says nothing about this minute. Here we
+    // look at how much CPU time passed between two samples.
+    const seconds = prev ? (at - prev.at) / 1000 : 0
+    const share = new Map()
+    let busy = 0
+    if (seconds > 0.2) {
+      for (const [pid, p] of procs) {
+        const was = prev.cpu.get(pid)
+        if (was === undefined) continue // born after the last sample: it has no before
+        const used = Math.max(0, p.cpu - was) / seconds
+        share.set(pid, used)
+        busy += used
+      }
+    }
+
+    prev = { at, cpu: new Map([...procs].map(([pid, p]) => [pid, p.cpu])) }
+    snap = {
+      at,
+      procs,
+      kids: childrenOf(procs),
+      share,
+      // Without a previous sample the CPU is not known yet: better to say so than invent it.
+      cpu: seconds > 0.2 ? Math.min(1, busy / CORES) : null,
+      mem,
+      swap: sw,
+      pressure: verdict(level, mem),
+    }
+  } catch {
+    /* one bad reading does not switch off what was already known */
+  } finally {
+    running = false
+  }
+}
+setInterval(cycle, TTL).unref()
+
+// ── What is known right now ───────────────────────────────────────────────────
+/**
+ * What a session weighs: its whole subtree. `top` is the three biggest processes inside it,
+ * and that is the answer to "why is this terminal eating so much".
+ */
+export function loadOf(pid) {
+  if (!snap || !pid || !snap.procs.has(pid)) return null
+  const pids = subtree(snap.kids, pid)
+  let rss = 0
+  let cpu = 0
+  // By name, not by process: Chrome opens ten of them and seeing them listed one by one says
+  // nothing, while "Google Chrome 562 MB" says everything.
+  const byName = new Map()
+  for (const p of pids) {
+    const proc = snap.procs.get(p)
+    if (!proc) continue
+    rss += proc.rss
+    cpu += snap.share.get(p) ?? 0
+    const name = shortName(proc.cmd)
+    byName.set(name, (byName.get(name) ?? 0) + proc.rss)
+  }
+  return { rss, cpu: snap.cpu === null ? null : cpu / CORES, procs: pids.size, top: heaviest(byName) }
+}
+
+/**
+ * How the machine is doing, and what is taking it up that is not a k0 session. `others` exists
+ * so k0 does not take blame that belongs to Chrome: with swap full, the sessions on their own
+ * often explain nothing.
+ */
+export function overview(sessionPids = []) {
+  if (!snap) return null
+  const mine = new Set()
+  for (const pid of sessionPids) if (snap.procs.has(pid)) for (const p of subtree(snap.kids, pid)) mine.add(p)
+
+  const byName = new Map()
+  for (const [pid, proc] of snap.procs) {
+    if (mine.has(pid)) continue
+    const name = shortName(proc.cmd)
+    byName.set(name, (byName.get(name) ?? 0) + proc.rss)
+  }
+
+  return {
+    cpu: snap.cpu,
+    mem: snap.mem,
+    swap: snap.swap,
+    pressure: snap.pressure,
+    others: heaviest(byName),
+    at: snap.at,
+  }
+}
+
+/** The three heaviest names, biggest first. */
+const heaviest = (byName) =>
+  [...byName]
+    .map(([name, rss]) => ({ name, rss }))
+    .sort((a, b) => b.rss - a.rss)
+    .slice(0, 3)
+
+/**
+ * A name worth showing, worked out from the command line. macOS applications first, which
+ * carry their real name in the bundle path — and it is also the only way to get them right,
+ * given that "Google Chrome" has a space in it. Then the interpreters, which on their own
+ * would only ever say "node": there, the name is the script they are running.
+ */
+export function shortName(cmd) {
+  const app = /\/([^/]+)\.app\//.exec(cmd)
+  if (app) return app[1]
+
+  const argv = String(cmd ?? '').trim().split(/\s+/)
+  const base = (s) => (s || '').split(/[/\\]/).pop()
+  const first = base(argv[0]).replace(/\.exe$/i, '')
+  if (!RUNNERS.has(first)) return first || 'unknown'
+
+  // `npm exec chrome-devtools-mcp@latest --flag` → chrome-devtools-mcp
+  for (const arg of argv.slice(1)) {
+    if (arg.startsWith('-') || VERBS.has(arg)) continue
+    const name = base(arg).replace(/@[^@]*$/, '')
+    // Only if it looks like a program name: behind `node -e` there is code, and a fragment of
+    // code as a name would be worse than "node".
+    return /^[\w.@-]+$/.test(name) ? name : first
+  }
+  return first
+}
+
+const RUNNERS = new Set([
+  'node', 'npm', 'npx', 'python', 'python3', 'ruby', 'sh', 'bash', 'zsh', 'deno', 'bun',
+  'powershell', 'pwsh', 'cmd',
+])
+const VERBS = new Set(['exec', 'run', 'run-script', '-c', 'start', 'test'])

package/server/mode.js

@@ -0,0 +1,182 @@
+import * as db from './db.js'
+import { power, capabilities } from '../platform/index.js'
+
+// ── The four modes ────────────────────────────────────────────────────────────
+// How awake the machine has to stay while sessions are working. A four-step scale, not two
+// switches: because the two things were never independent. In driving mode the display MUST
+// stay on — there is no point watching the board from across the room on a screen that turns
+// itself off — and sitting in front of it programming is a third case that two booleans had
+// no way to express.
+//
+//   sleep    the machine sleeps as it normally would
+//   away     it does not sleep any more, not even with the lid closed; the display still does
+//   nerd     you are sitting there: the display stays on too
+//   driving  like nerd, plus everything set large — board and terminals
+//
+// Each line includes the one above it: that is what makes the four buttons a scale rather
+// than a list. The only difference between nerd and driving is the size of the text.
+//
+// There are two levers, and an idle inhibitor alone is not enough on macOS: its assertions
+// are all *idle* assertions, which stop sleep from inactivity but not the sleep that fires
+// when the lid closes. That one takes a system flag and root. On Linux and Windows the lid
+// belongs to a machine-wide setting that k0 refuses to rewrite on your behalf — see the notes
+// in the platform adapters — so there the lid switch reports itself unavailable rather than
+// promising something it will not deliver.
+
+/**
+ * What each mode means, in one place: anyone who wants to know what a mode does reads it
+ * from here, and nobody works it out again for themselves.
+ *
+ * `inhibit` is the level handed to the platform: 'system' stops idle sleep, 'display' also
+ * keeps the screen on. The difference between away and nerd is exactly that word.
+ */
+export const MODES = {
+  sleep: { inhibit: null, lid: false, driving: false },
+  away: { inhibit: 'system', lid: true, driving: false },
+  nerd: { inhibit: 'display', lid: true, driving: false },
+  driving: { inhibit: 'display', lid: true, driving: true },
+}
+
+/** Sleepiest to most awake: this is the order of the buttons on the board. */
+export const ORDER = ['sleep', 'away', 'nerd', 'driving']
+
+/** The one to start from, and the one to fall back to when an unknown word arrives. */
+export const DEFAULT = 'away'
+
+/** The key in `pref`, and the two it grew out of as k0 changed its mind about names. */
+export const KEY = 'mode'
+export const LEGACY_KEYS = ['modo', 'caffe']
+
+/** Values written by older versions, and what they mean now. */
+const LEGACY_VALUES = { sonno: 'sleep', caffe: 'away', nerd: 'nerd', driving: 'driving' }
+
+/**
+ * Below this charge, and only on battery, k0 lets go of the lid. A machine forbidden to sleep
+ * does not merely drain: it reaches zero and dies outright, which is worse than a session
+ * left waiting. The idle inhibitor stays — that one is harmless — and everything resumes by
+ * itself as soon as the power is back.
+ */
+export const THRESHOLD = 15
+
+let mode = DEFAULT
+let lidHeld = false // is the lid block really in force RIGHT NOW
+let supply = { onAcPower: true, charge: null } // the power as it was last looked at
+let stopped = false // the kettle is already off the hob (shutting down)
+
+// ── Read, do not imagine ──────────────────────────────────────────────────────
+
+/** A word that is not a mode must not blow anything up: it falls back to the default. */
+export const normalise = (m) => {
+  const s = String(m)
+  if (Object.hasOwn(MODES, s)) return s
+  if (Object.hasOwn(LEGACY_VALUES, s)) return LEGACY_VALUES[s]
+  return DEFAULT
+}
+
+/**
+ * Whether the lid block belongs on or off: the whole rule, in one place. The mode asks for it,
+ * except on a nearly flat battery — and except where the platform cannot do it at all.
+ *
+ * `supported` defaults to what this machine can do and is passed explicitly by the tests, so the
+ * rule can be checked on any platform rather than only on the one that happens to support it.
+ */
+export function lidWanted({ mode: m, onAcPower, charge, supported = capabilities.power.lidSleep }) {
+  if (!supported) return false
+  if (!MODES[normalise(m)].lid) return false
+  if (onAcPower || charge === null) return true
+  return charge >= THRESHOLD
+}
+
+// ── What the rest of the house knows ─────────────────────────────────────────
+
+export const current = () => mode
+export const lid = () => lidHeld
+
+/**
+ * Whether the text goes large. `launcher.js` asks for every window that is born, and it is
+ * the only thing driving mode needs the outside world to know.
+ */
+export const isDriving = () => MODES[mode].driving
+
+/**
+ * Why we are in the state we are in. The board needs it to say so in words above the lit
+ * button: a mode that promises the lid closed and cannot deliver has to be able to say so,
+ * otherwise it is promising something it does not do.
+ */
+export function reason() {
+  if (mode === 'sleep') return 'sleep'
+  if (lidHeld) return 'full'
+  if (!capabilities.power.lidSleep) return 'unsupported'
+  if (!lidWanted({ mode, ...supply })) return 'battery'
+  return 'no-permission'
+}
+
+/**
+ * Brings the world into line with the mode. At the end it reads back how it actually turned
+ * out instead of trusting the command it just gave: what matters is what the machine is
+ * doing, not what we believed we had told it.
+ */
+export async function apply() {
+  supply = await power.state()
+  power.inhibit(MODES[mode].inhibit)
+  await power.setLidSleepBlocked(lidWanted({ mode, ...supply }))
+  lidHeld = await power.lidSleepBlocked()
+}
+
+export async function setMode(m) {
+  mode = normalise(m)
+  db.setPref(KEY, mode)
+  await apply()
+}
+
+/**
+ * At server startup. Puts the machine back the way you left it — driving included, which it
+ * used not to remember — and repairs the awkward case: mode `sleep` but the lid block left at
+ * 1 by a server that died badly. Putting it back to 0 is part of the job, otherwise the
+ * machine never sleeps again and nobody knows why.
+ */
+export async function start() {
+  migrateLegacyPref()
+  mode = normalise(db.getPref(KEY, DEFAULT))
+  await apply()
+}
+
+/**
+ * k0 has renamed this preference twice: `caffe` when it was a single on/off switch, then
+ * `modo` when it became a scale, and now `mode`. Each old key is read once and retired, so an
+ * upgraded k0 does not start over from the default.
+ */
+function migrateLegacyPref() {
+  for (const legacy of LEGACY_KEYS) {
+    const value = db.getPref(legacy, null)
+    if (value === null) continue
+    if (db.getPref(KEY, null) === null) {
+      // The oldest key held '1' or '0' rather than a mode name.
+      db.setPref(KEY, value === '0' ? 'sleep' : value === '1' ? 'away' : normalise(value))
+    }
+    db.dropPref(legacy)
+  }
+}
+
+/**
+ * A check-up round, which the server's `tick` calls once a minute. It does two things: follow
+ * the battery down (and the power coming back), and put the inhibitor back up if something
+ * killed it from outside.
+ */
+export async function guard() {
+  if (stopped) return
+  await apply()
+}
+
+/**
+ * The last gesture on the way out. Synchronous on purpose: from `process.on('exit')` nothing
+ * asynchronous gets to start any more, and this is the net that stops a machine being left
+ * awake forever because k0 went away while it was on. The preference is left alone: next
+ * time, `start()` puts everything back.
+ */
+export function stopNow() {
+  if (stopped) return
+  stopped = true
+  power.releaseSync()
+  lidHeld = false
+}

package/server/paths.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Where k0 keeps the things that must outlive a reinstall.
+ *
+ * Until 0.1.0 the database sat next to the source, which was fine while k0 only ever ran
+ * from a checkout. It stopped being fine the moment `npx k0-board` became the normal way
+ * in: npx unpacks into a cache directory that npm is free to wipe, so anything written
+ * there is on borrowed time. Data now lives in a directory owned by the user, and the
+ * installed copy of the app is disposable.
+ *
+ *   ~/.k0/k0.db      the board
+ *   ~/.k0/app/       the installed copy of k0 (written by `k0-board install`)
+ *   ~/.k0/logs/      service stdout/stderr
+ *   ~/.k0/cache/     pasted images, the Chrome profile used for PDF export
+ *
+ * On Windows the same tree goes under %LOCALAPPDATA%\k0, which is the local-only,
+ * not-roamed location Windows expects for this kind of state.
+ */
+export const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
+
+const DEFAULT_HOME =
+  process.platform === 'win32'
+    ? path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'k0')
+    : path.join(os.homedir(), '.k0')
+
+export const HOME = process.env.K0_HOME ? path.resolve(process.env.K0_HOME) : DEFAULT_HOME
+
+export const APP_DIR = path.join(HOME, 'app')
+export const LOG_DIR = path.join(HOME, 'logs')
+export const CACHE_DIR = path.join(HOME, 'cache')
+
+/** `K0_DB` is how the tests stay away from the real board. See the guard in db.js. */
+export const DB_PATH = process.env.K0_DB || path.join(HOME, 'k0.db')
+
+export function ensureDirs() {
+  for (const dir of [HOME, LOG_DIR, CACHE_DIR]) fs.mkdirSync(dir, { recursive: true })
+}
+
+/**
+ * Move a pre-0.1.0 database out of the checkout and into the home directory.
+ *
+ * Only ever runs once, and only when there is nothing to overwrite: if the new location
+ * already holds a database, the old file is left alone rather than merged or clobbered.
+ * The write-ahead log and shared-memory files come along, because leaving them behind
+ * would silently drop whatever had not been checkpointed yet.
+ *
+ * And only ever into the DEFAULT home. Pointing `K0_HOME` somewhere else is how you run a
+ * second k0 against a scratch directory, and a move is not undoable by the person watching it
+ * happen: doing it there would drag the real board into a temporary folder while the real
+ * server still had it open. Verified the hard way.
+ */
+export function migrateLegacyDatabase() {
+  if (process.env.K0_DB) return false
+  if (HOME !== DEFAULT_HOME) return false
+  const legacy = path.join(ROOT, 'k0.db')
+  if (!fs.existsSync(legacy) || fs.existsSync(DB_PATH)) return false
+  ensureDirs()
+  for (const suffix of ['', '-wal', '-shm']) {
+    const from = legacy + suffix
+    if (fs.existsSync(from)) fs.renameSync(from, DB_PATH + suffix)
+  }
+  return true
+}