k0-board 0.1.0

package/platform/shared/ps.js

@@ -0,0 +1,40 @@
+/**
+ * Reading a process table, the parts that are the same everywhere.
+ *
+ * macOS and Linux both have a `ps` that can be asked for exactly the five fields k0 wants,
+ * in exactly that order, so one parser serves both. Windows has no `ps`, but its adapter
+ * builds the same shape out of CIM data, which is why the shape and not the command is what
+ * lives here.
+ */
+
+/**
+ * One `ps` line per process: pid, parent, resident memory in KB, CPU time consumed since it
+ * was born, and the command — which contains spaces, so it takes everything that is left.
+ */
+export function parsePs(out) {
+  const procs = new Map()
+  for (const line of String(out ?? '').split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line)
+    if (!m) continue
+    procs.set(Number(m[1]), {
+      ppid: Number(m[2]),
+      rss: Number(m[3]) * 1024,
+      cpu: cpuSeconds(m[4]),
+      cmd: m[5],
+    })
+  }
+  return procs
+}
+
+/**
+ * CPU time the way `ps` writes it: `MM:SS.ss` usually, `HH:MM:SS` when it adds up, with a
+ * leading `DD-` for processes that have been up for days.
+ */
+export function cpuSeconds(s) {
+  const m = /^(?:(\d+)-)?(\d+):(\d+)(?::(\d+))?(?:\.(\d+))?$/.exec(String(s ?? '').trim())
+  if (!m) return 0
+  const [, d, a, b, c, frac] = m
+  // Three groups means hours:minutes:seconds, two means minutes:seconds.
+  const base = c === undefined ? Number(a) * 60 + Number(b) : Number(a) * 3600 + Number(b) * 60 + Number(c)
+  return Number(d || 0) * 86400 + base + Number(`0.${frac || 0}`)
+}

package/platform/shared/run.js

@@ -0,0 +1,99 @@
+import { execFile, execFileSync } from 'node:child_process'
+import { promisify } from 'node:util'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const execFileAsync = promisify(execFile)
+
+const DEFAULT_TIMEOUT = 5000
+
+/**
+ * Run a command and get its stdout back.
+ *
+ * Everything that talks to the operating system goes through here rather than through a
+ * shell, so a directory name with a space or a quote in it stays a directory name instead
+ * of turning into two arguments.
+ */
+export async function run(file, args = [], opts = {}) {
+  const { stdout } = await execFileAsync(file, args, { timeout: DEFAULT_TIMEOUT, ...opts })
+  return stdout
+}
+
+/** Same, but never throws: a command that is not there returns an empty string. */
+export async function runQuiet(file, args = [], opts = {}) {
+  try {
+    return await run(file, args, opts)
+  } catch {
+    return ''
+  }
+}
+
+export function runSync(file, args = [], opts = {}) {
+  return execFileSync(file, args, { encoding: 'utf8', timeout: DEFAULT_TIMEOUT, ...opts })
+}
+
+export function runSyncQuiet(file, args = [], opts = {}) {
+  try {
+    return runSync(file, args, opts)
+  } catch {
+    return ''
+  }
+}
+
+const found = new Map()
+
+/**
+ * Find an executable, preferring a known absolute path and falling back to PATH.
+ *
+ * The absolute path comes first for a reason that only shows up in production: the server
+ * runs as a background service, and a login shell's PATH is not what it inherits. Under
+ * launchd it is barely more than /usr/bin:/bin. Looking the binary up by name alone works
+ * perfectly from a terminal and then fails the moment k0 is installed for real.
+ *
+ * The reverse fallback matters too — Homebrew, Nix and the various Linux distributions all
+ * disagree about where things live — so this tries the known locations, then the PATH, and
+ * only then gives up.
+ *
+ * @param {string} name  bare command name, e.g. 'git'
+ * @param {string[]} candidates  absolute paths to try first
+ * @returns {string|null}
+ */
+export function which(name, candidates = []) {
+  if (found.has(name)) return found.get(name)
+  const tried = [...candidates]
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue
+    for (const ext of process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : ['']) {
+      tried.push(path.join(dir, name + ext))
+    }
+  }
+  for (const candidate of tried) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK)
+      found.set(name, candidate)
+      return candidate
+    } catch {
+      /* keep looking */
+    }
+  }
+  found.set(name, null)
+  return null
+}
+
+/** `which`, but it throws a sentence a user can act on instead of ENOENT. */
+export function need(name, candidates = [], hint = '') {
+  const bin = which(name, candidates)
+  if (bin) return bin
+  throw new Error(`k0 needs "${name}" but could not find it on this machine.${hint ? ` ${hint}` : ''}`)
+}
+
+/** Is this process still alive? Signal 0 asks without sending anything. */
+export function alive(pid) {
+  if (!pid) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return err.code === 'EPERM'
+  }
+}

package/platform/shared/tmux.js

@@ -0,0 +1,242 @@
+import { spawn } from 'node:child_process'
+import { run, runQuiet, which } from './run.js'
+
+/**
+ * A terminal, backed by tmux.
+ *
+ * This is the choice that makes everything else possible outside macOS. k0 does not just
+ * need to *start* a terminal — it needs to rename it, read back what is on its screen to
+ * know when Claude Code's interface is ready, and put a prompt in front of you without
+ * sending it. On macOS, AppleScript does all three. On Linux there is no equivalent: every
+ * terminal emulator is its own island, and most of them cannot be addressed at all once
+ * they are running.
+ *
+ * tmux can. It creates a session, renames it, captures the pane, sends literal keys without
+ * a newline, and kills it cleanly — and it does all of that identically on every emulator,
+ * because the emulator is reduced to a window that happens to be attached. Which also means
+ * a session survives its window being closed: you can reattach with `tmux attach -t <name>`
+ * and find your work exactly where you left it.
+ *
+ * What tmux cannot do is move, resize or restyle the window around it. That belongs to the
+ * window manager, and it is why `windows` and `font` are probed rather than assumed.
+ */
+
+const TMUX = () => which('tmux')
+
+/** Terminal emulators, in the order they are tried, and how each runs a command. */
+const EMULATORS = [
+  { bin: 'gnome-terminal', args: (cmd) => ['--', ...cmd] },
+  { bin: 'konsole', args: (cmd) => ['-e', ...cmd] },
+  { bin: 'kitty', args: (cmd) => [...cmd] },
+  { bin: 'alacritty', args: (cmd) => ['-e', ...cmd] },
+  { bin: 'wezterm', args: (cmd) => ['start', '--', ...cmd] },
+  { bin: 'xfce4-terminal', args: (cmd) => ['-x', ...cmd] },
+  { bin: 'tilix', args: (cmd) => ['-e', ...cmd] },
+  { bin: 'x-terminal-emulator', args: (cmd) => ['-e', ...cmd] },
+  { bin: 'xterm', args: (cmd) => ['-e', ...cmd] },
+]
+
+/**
+ * Which emulator to open. `K0_TERMINAL` wins, because no list of ours will ever cover every
+ * terminal anybody uses, and being wrong about it should not mean being stuck with it.
+ */
+export function findEmulator() {
+  const forced = process.env.K0_TERMINAL
+  if (forced) {
+    const bin = which(forced)
+    if (bin) return { bin, args: (cmd) => ['-e', ...cmd], name: forced }
+  }
+  for (const e of EMULATORS) {
+    const bin = which(e.bin)
+    if (bin) return { ...e, bin, name: e.bin }
+  }
+  return null
+}
+
+const XDOTOOL = () => which('xdotool')
+const WMCTRL = () => which('wmctrl')
+
+/**
+ * Wayland deliberately does not let one application move another's windows, so there is no
+ * xdotool equivalent and there is not going to be. Under Wayland k0 says window placement is
+ * unavailable rather than silently doing nothing.
+ */
+export const isWayland = () =>
+  (process.env.XDG_SESSION_TYPE || '').toLowerCase() === 'wayland' || !!process.env.WAYLAND_DISPLAY
+
+export const canPlaceWindows = () => !isWayland() && (!!XDOTOOL() || !!WMCTRL())
+
+let counter = 0
+const sessionName = () => `k0-${process.pid}-${++counter}`
+
+const exists = async (session) => {
+  const out = await runQuiet(TMUX(), ['has-session', '-t', `=${session}`]).catch(() => '')
+  // `has-session` says what it thinks through the exit code, and runQuiet swallows that, so
+  // ask for the list instead and look for the name.
+  const list = await runQuiet(TMUX(), ['list-sessions', '-F', '#{session_name}'])
+  return String(list).split('\n').includes(session) || !!out
+}
+
+export async function open({ command, title }) {
+  const tmux = TMUX()
+  if (!tmux) throw new Error('k0 needs tmux to drive terminals on this platform. Install it and try again.')
+  const session = sessionName()
+
+  // The session runs the command directly rather than a shell that then runs it: when Claude
+  // Code exits, the session ends, which is what makes a finished card's terminal disappear
+  // instead of leaving an idle shell behind.
+  await run(tmux, ['new-session', '-d', '-s', session, '-n', title || session, command])
+  // Off by default, and worth turning on: it is what puts the card's name in the window's
+  // title bar rather than "tmux".
+  await runQuiet(tmux, ['set-option', '-t', session, 'set-titles', 'on'])
+  await runQuiet(tmux, ['set-option', '-t', session, 'set-titles-string', title || session])
+
+  const emulator = findEmulator()
+  if (emulator) {
+    const child = spawn(emulator.bin, emulator.args([tmux, 'attach', '-t', session]), {
+      stdio: 'ignore',
+      detached: true,
+    })
+    child.unref()
+  }
+  return session
+}
+
+export async function setTitle(handle, title) {
+  if (!handle) return false
+  const tmux = TMUX()
+  if (!tmux) return false
+  const ok = await runQuiet(tmux, ['rename-window', '-t', `${handle}:0`, title])
+  await runQuiet(tmux, ['set-option', '-t', handle, 'set-titles-string', title])
+  return ok !== null
+}
+
+export async function readScreen(handle) {
+  if (!handle) return null
+  const tmux = TMUX()
+  if (!tmux) return null
+  try {
+    return await run(tmux, ['capture-pane', '-p', '-t', handle])
+  } catch {
+    return null // session gone
+  }
+}
+
+/**
+ * `send-keys -l` sends the text literally and adds nothing: no newline, no key interpretation.
+ * It is the closest thing to a paste there is, and unlike a real paste it needs no clipboard,
+ * no focus and no accessibility permission — which makes it more reliable here than the macOS
+ * path it replaces.
+ */
+export async function paste(text, handle) {
+  const tmux = TMUX()
+  if (!tmux || !handle) return { pasted: false, error: 'no terminal session' }
+  try {
+    await run(tmux, ['send-keys', '-t', handle, '-l', text])
+    return { pasted: true }
+  } catch (err) {
+    return { pasted: false, error: String(err.stderr || err.message).trim() }
+  }
+}
+
+export async function type(text, handle) {
+  const tmux = TMUX()
+  if (!tmux || !handle) return { written: false }
+  try {
+    await run(tmux, ['send-keys', '-t', handle, '-l', text])
+    await run(tmux, ['send-keys', '-t', handle, 'Enter'])
+    return { written: true }
+  } catch (err) {
+    return { written: false, error: String(err.stderr || err.message).trim() }
+  }
+}
+
+export async function close({ handle, pid }) {
+  if (pid) {
+    try {
+      process.kill(pid, 'SIGTERM')
+      for (let i = 0; i < 20; i++) {
+        await new Promise((r) => setTimeout(r, 100))
+        try {
+          process.kill(pid, 0)
+        } catch {
+          break
+        }
+      }
+    } catch {
+      /* already dead, or not ours */
+    }
+  }
+  if (!handle) return { closed: false }
+  const tmux = TMUX()
+  if (!tmux) return { closed: false }
+  const before = await exists(handle)
+  await runQuiet(tmux, ['kill-session', '-t', handle])
+  return { closed: before }
+}
+
+/** The window showing this session, found by the title tmux set on it. */
+async function windowId(handle) {
+  const xdotool = XDOTOOL()
+  if (!xdotool) return null
+  const out = await runQuiet(xdotool, ['search', '--name', handle])
+  return String(out).trim().split('\n').filter(Boolean).pop() || null
+}
+
+export async function focus(handle) {
+  if (!handle) return { ok: false, error: 'This card has no terminal of its own' }
+  if (!canPlaceWindows()) return { ok: false, error: 'k0 cannot raise windows on this desktop' }
+  const id = await windowId(handle)
+  if (!id) return { ok: false, error: 'That window is gone' }
+  await runQuiet(XDOTOOL(), ['windowactivate', id])
+  return { ok: true }
+}
+
+/**
+ * Geometry, best effort. There is no NSScreen here to ask for the usable area net of panels
+ * and docks, so the work area comes from the window manager's own `_NET_WORKAREA` by way of
+ * xdotool, and the same 86% margin as everywhere else is applied to it.
+ */
+export async function relayout(handles) {
+  if (!canPlaceWindows()) return { touched: 0 }
+  const xdotool = XDOTOOL()
+  const geom = await runQuiet(xdotool, ['getdisplaygeometry'])
+  const [sw, sh] = String(geom).trim().split(/\s+/).map(Number)
+  if (!sw || !sh) return { touched: 0 }
+  const w = Math.round(sw * 0.86)
+  const h = Math.round(sh * 0.86)
+  const x = Math.round((sw - w) / 2)
+  const y = Math.round((sh - h) / 2)
+  let touched = 0
+  for (const handle of handles || []) {
+    const id = await windowId(handle)
+    if (!id) continue
+    await runQuiet(xdotool, ['windowmove', id, String(x), String(y)])
+    await runQuiet(xdotool, ['windowsize', id, String(w), String(h)])
+    touched++
+  }
+  return { touched }
+}
+
+/**
+ * Font size belongs to the emulator, and every emulator spells it differently — some only in
+ * a config file that is read at startup. There is no honest generic answer, so k0 says it
+ * cannot and driving mode changes only the board's own text.
+ */
+export async function setFont() {
+  return { touched: 0 }
+}
+
+export async function defaultFontSize() {
+  return 12
+}
+
+export const capabilities = () => ({
+  windows: canPlaceWindows(),
+  font: false,
+  readScreen: !!TMUX(),
+  pasteWithoutSending: !!TMUX(),
+  title: !!TMUX(),
+})
+
+export { posixCommand as buildCommand } from './command.js'

package/platform/win32/index.js

@@ -0,0 +1,53 @@
+import path from 'node:path'
+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 shell from './shell.js'
+import * as service from './service.js'
+import { NO_CAPABILITIES } from '../contract.js'
+import { which } from '../shared/run.js'
+
+export const name = 'Windows'
+
+export const trayScript = path.join(path.dirname(fileURLToPath(import.meta.url)), 'tray.ps1')
+
+const hasPowerShell = () => !!(which('pwsh') || which('powershell'))
+
+export const capabilities = {
+  ...NO_CAPABILITIES,
+  terminal: terminal.capabilities(),
+  power: power.capabilities(),
+  metrics: metrics.capabilities(),
+  service: service.capabilities(),
+  tray: hasPowerShell(),
+  revealInFileManager: true,
+}
+
+export const notes = {
+  ...power.notes,
+  ...metrics.notes,
+  'terminal.readScreen':
+    'Windows gives no way to read what is printed inside another process’s console, so k0 ' +
+    'cannot tell exactly when Claude Code has finished starting: it waits a fixed moment ' +
+    'instead. On a slow machine the prompt can arrive early — press Escape, then paste it ' +
+    'again from the card.',
+  'terminal.title':
+    'Windows Terminal owns its tab titles, so renaming a card does not rename a window that ' +
+    'is already open. The new name shows up next time the session starts.',
+  'terminal.font':
+    'Font size lives in your terminal’s own profile, which k0 will not rewrite, so driving ' +
+    'mode enlarges the board but not the terminals.',
+  ...(hasPowerShell()
+    ? {}
+    : {
+        'terminal.windows':
+          'PowerShell was not found. k0 needs it to open, place and raise terminal windows on ' +
+          'Windows.',
+      }),
+}
+
+export { terminal, power, metrics, shell, service }
+
+/** Nothing on Windows reaches outside k0's own files, so there is nothing to consent to. */
+export const extras = []

package/platform/win32/metrics.js

@@ -0,0 +1,72 @@
+import os from 'node:os'
+import { psJson } from './powershell.js'
+
+/**
+ * Process and memory figures on Windows, out of CIM.
+ *
+ * There is no `ps`, so the shape the rest of k0 expects is built here instead of parsed. The
+ * fields line up one for one: WorkingSetSize is resident memory, and KernelModeTime plus
+ * UserModeTime is CPU time — in 100-nanosecond ticks, which is where the division comes from.
+ */
+
+export async function processes() {
+  const rows = await psJson(
+    `@(Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId, WorkingSetSize, KernelModeTime, UserModeTime, CommandLine, Name)`,
+    []
+  )
+  const procs = new Map()
+  for (const row of Array.isArray(rows) ? rows : [rows].filter(Boolean)) {
+    const pid = Number(row.ProcessId)
+    if (!pid) continue
+    procs.set(pid, {
+      ppid: Number(row.ParentProcessId) || 0,
+      rss: Number(row.WorkingSetSize) || 0,
+      cpu: (Number(row.KernelModeTime || 0) + Number(row.UserModeTime || 0)) / 1e7,
+      cmd: row.CommandLine || row.Name || '',
+    })
+  }
+  return procs
+}
+
+/**
+ * Windows has no equivalent of macOS's wired/compressed split, so those come back zero and
+ * the whole of "used" is attributed to applications. `cached` is the standby list, which is
+ * the closest thing to file-backed pages — memory nobody is short of.
+ */
+export async function memory() {
+  const info = await psJson(
+    `Get-CimInstance Win32_OperatingSystem | Select-Object TotalVisibleMemorySize, FreePhysicalMemory`,
+    null
+  )
+  const total = info ? Number(info.TotalVisibleMemorySize) * 1024 : os.totalmem()
+  const free = info ? Number(info.FreePhysicalMemory) * 1024 : os.freemem()
+  const used = Math.max(0, total - free)
+  return { total, used, app: used, wired: 0, compressed: 0, cached: 0 }
+}
+
+/** The page file is Windows's swap. A machine with none reports zeroes, which is correct. */
+export async function swap() {
+  const page = await psJson(
+    `Get-CimInstance Win32_PageFileUsage | Select-Object AllocatedBaseSize, CurrentUsage`,
+    null
+  )
+  if (!page) return { total: 0, used: 0 }
+  const rows = Array.isArray(page) ? page : [page]
+  return {
+    total: rows.reduce((n, r) => n + Number(r.AllocatedBaseSize || 0) * 1024 * 1024, 0),
+    used: rows.reduce((n, r) => n + Number(r.CurrentUsage || 0) * 1024 * 1024, 0),
+  }
+}
+
+/** Windows publishes no pressure verdict, so the board judges by how full memory is. */
+export async function pressureLevel() {
+  return 1
+}
+
+export const capabilities = () => ({ pressure: false, swap: true })
+
+export const notes = {
+  'metrics.pressure':
+    'Windows does not publish a memory-pressure verdict the way macOS and Linux do, so k0 ' +
+    'judges by how full memory is instead.',
+}

package/platform/win32/power.js

@@ -0,0 +1,109 @@
+import { spawn } from 'node:child_process'
+import { psJson, POWERSHELL } from './powershell.js'
+
+/**
+ * Keeping a Windows machine awake.
+ *
+ * `SetThreadExecutionState` is the Windows equivalent of an idle assertion: a thread declares
+ * that the system (and optionally the display) is needed, and the declaration lasts exactly
+ * as long as that thread does. So k0 holds it in a small PowerShell process and kills that
+ * process to let go — the same shape as `caffeinate` on macOS and `systemd-inhibit` on Linux.
+ *
+ * The lid is not here. On Windows lid behaviour is a power-plan setting changed with
+ * `powercfg`, it applies to the whole machine, and it survives k0 being uninstalled. That is
+ * not something a board of sticky notes should rewrite on your behalf, so the switch is
+ * reported as unavailable with a note saying where to change it yourself.
+ */
+
+const ES_CONTINUOUS = 0x80000000
+const ES_SYSTEM_REQUIRED = 0x00000001
+const ES_DISPLAY_REQUIRED = 0x00000002
+
+let child = null
+let activeLevel = null
+
+export async function state() {
+  const battery = await psJson(
+    `Get-CimInstance Win32_Battery | Select-Object -First 1 EstimatedChargeRemaining, BatteryStatus`,
+    null
+  )
+  if (!battery) return { onAcPower: true, charge: null }
+  // BatteryStatus 2 is "AC power"; 1 is "discharging". Anything else is a charging state,
+  // which still means the mains are connected.
+  return {
+    onAcPower: Number(battery.BatteryStatus) !== 1,
+    charge: Number.isFinite(Number(battery.EstimatedChargeRemaining))
+      ? Number(battery.EstimatedChargeRemaining)
+      : null,
+  }
+}
+
+export function inhibit(level) {
+  if (activeLevel === level) return
+  release()
+  if (!level) return
+  const shell = POWERSHELL()
+  if (!shell) return
+  activeLevel = level
+
+  const flags =
+    ES_CONTINUOUS | ES_SYSTEM_REQUIRED | (level === 'display' ? ES_DISPLAY_REQUIRED : 0)
+
+  // The state is held for the lifetime of this process and released the moment it exits,
+  // including when it is killed outright — which is the safety net that stops a machine
+  // being left awake because k0 went away badly.
+  const script = `
+Add-Type -Namespace K0 -Name Power -MemberDefinition @'
+  [DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint flags);
+'@
+[K0.Power]::SetThreadExecutionState(${flags >>> 0}) | Out-Null
+while ($true) { Start-Sleep -Seconds 3600 }`
+
+  const spawned = spawn(shell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script], {
+    stdio: 'ignore',
+  })
+  child = spawned
+  const forget = () => {
+    if (child !== spawned) return
+    child = null
+    activeLevel = null
+  }
+  spawned.on('error', forget)
+  spawned.on('exit', forget)
+  spawned.unref()
+}
+
+export function release() {
+  activeLevel = null
+  if (!child) return
+  try {
+    child.kill()
+  } catch {
+    /* already gone */
+  }
+  child = null
+}
+
+export async function setLidSleepBlocked() {}
+
+export async function lidSleepBlocked() {
+  return false
+}
+
+export function releaseSync() {
+  release()
+}
+
+export const capabilities = () => ({
+  keepAwake: !!POWERSHELL(),
+  keepDisplayAwake: !!POWERSHELL(),
+  lidSleep: false,
+  battery: !!POWERSHELL(),
+})
+
+export const notes = {
+  'power.lidSleep':
+    'On Windows the lid is a power-plan setting. To keep working with the lid closed, set ' +
+    '"When I close the lid" to "Do nothing" in Control Panel → Power Options. k0 will not ' +
+    'change a machine-wide power setting for you.',
+}

package/platform/win32/powershell.js

@@ -0,0 +1,44 @@
+import { run, runQuiet, which } from '../shared/run.js'
+
+/**
+ * PowerShell is how k0 talks to Windows.
+ *
+ * Everything Windows-specific here — window handles, process trees, execution state, the
+ * tray icon — is reachable from PowerShell without installing anything, which is the whole
+ * reason it is used rather than a native module. k0 has no dependencies and is not about to
+ * grow one that needs a compiler on the user's machine.
+ *
+ * PowerShell 7 (`pwsh`) is preferred where it exists and Windows PowerShell 5.1 is the
+ * fallback, because 5.1 is on every Windows install and the scripts here stay inside what
+ * both understand.
+ */
+
+export const POWERSHELL = () => which('pwsh') || which('powershell')
+
+const BASE_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command']
+
+export const ps = (script, opts = {}) => run(POWERSHELL(), [...BASE_ARGS, script], opts)
+
+export const psQuiet = (script, opts = {}) => runQuiet(POWERSHELL(), [...BASE_ARGS, script], opts)
+
+/**
+ * Ask PowerShell for JSON and get an object back.
+ *
+ * `-Depth 4` is not decoration: ConvertTo-Json truncates at depth 2 by default and silently
+ * turns anything deeper into the string "System.Object[]". `-AsArray`-less output also
+ * collapses a one-element list into a bare object, so single results are wrapped by the
+ * caller rather than trusted to arrive as a list.
+ */
+export async function psJson(script, fallback = null) {
+  const out = await psQuiet(`${script} | ConvertTo-Json -Depth 4 -Compress`)
+  const text = String(out).trim()
+  if (!text) return fallback
+  try {
+    return JSON.parse(text)
+  } catch {
+    return fallback
+  }
+}
+
+/** Single-quote a string for a PowerShell literal. */
+export const psq = (s) => `'${String(s).replace(/'/g, "''")}'`