omakit 0.1.9 → 0.2.0

package/tools/weigh/commands.mjs

@@ -0,0 +1,69 @@
+// The Omarchy commands `omakit weigh` runs, as a frozen table, and the one call
+// site that runs them.
+//
+// This is the one part of omakit that changes the user's own machine: it
+// restarts their shell. So what it can run is a list, not a search. Every
+// entry names its binary and its arguments; `run()` is the only spawn under
+// tools/weigh/ (tests/unit/read-only.test.mjs holds it to that), and the only
+// entry that takes an argument at run time is the shell pid lookup, which
+// needs the shell's configuration directory. No `quickshell kill`, no
+// `hyprctl`, no `systemctl` beyond reading the session's environment: the
+// restart is `omarchy-restart-shell`, the same command a person runs, with
+// its own lock check and its own readiness poll.
+
+import { spawnSync } from "node:child_process"
+
+export const COMMANDS = Object.freeze({
+  /** The session's environment, for OMARCHY_PATH: the shell that runs, not the one on PATH. */
+  sessionEnvironment: Object.freeze({ command: "systemctl", args: Object.freeze(["--user", "show-environment"]) }),
+  /** Exit 0 while the compositor holds a session lock; the check `omarchy-restart-shell` makes. */
+  sessionLocked: Object.freeze({ command: "omarchy-hyprland-session-locked", args: Object.freeze([]) }),
+  /** Is the shell running. */
+  ping: Object.freeze({ command: "omarchy-shell", args: Object.freeze(["shell", "ping"]) }),
+  /** Every installed plugin with id, name, kinds, enabled and firstParty: `listPlugins` verbatim. */
+  listPlugins: Object.freeze({ command: "omarchy", args: Object.freeze(["plugin", "list", "--json"]) }),
+  /** The effective shell configuration, defaults filled in. */
+  listShellConfig: Object.freeze({ command: "omarchy-shell", args: Object.freeze(["shell", "listShellConfig"]) }),
+  /** Every manifest with its source directory, without the shell. */
+  catalog: Object.freeze({ command: "omarchy-plugin-catalog", args: Object.freeze([]) }),
+  /** The shell's pid: `qs list -p <shell dir> --json`, the two extra arguments passed at run time. */
+  shellPid: Object.freeze({ command: "qs", args: Object.freeze(["list", "-p"]) }),
+  /** The shell's IPC targets and their functions: `qs ipc -p <shell dir> show`, read-only, for the compatibility preflight. */
+  ipcShow: Object.freeze({ command: "qs", args: Object.freeze(["ipc", "-p"]) }),
+  /** The restart, and the readiness poll that comes with it. */
+  restartShell: Object.freeze({ command: "omarchy-restart-shell", args: Object.freeze([]) }),
+  /** Clock ticks per second, for /proc/<pid>/stat. */
+  clockTicks: Object.freeze({ command: "getconf", args: Object.freeze(["CLK_TCK"]) }),
+})
+
+/**
+ * Run one entry of the table. Resolves through the caller's PATH, so a test
+ * puts stubs first on it; never a shell, never a string.
+ *
+ * @param {keyof typeof COMMANDS} name
+ * @param {{ env?: NodeJS.ProcessEnv, extra?: string[], timeoutMs?: number }} [options]
+ * @returns {{ ok: boolean, status: number|null, stdout: string, stderr: string, missing: boolean }}
+ */
+export function run(name, { env = process.env, extra = [], timeoutMs = 30_000 } = {}) {
+  const entry = COMMANDS[name]
+  if (!entry) throw new Error(`weigh: no command named ${name}`)
+  const result = spawnSync(entry.command, [...entry.args, ...extra], {
+    encoding: "utf8",
+    env,
+    timeout: timeoutMs,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  return {
+    ok: result.status === 0 && !result.error,
+    status: result.status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    missing: result.error?.code === "ENOENT",
+  }
+}
+
+/** The command line an entry runs, for a message that names it. */
+export function commandLine(name, extra = []) {
+  const entry = COMMANDS[name]
+  return [entry.command, ...entry.args, ...extra].join(" ")
+}

package/tools/weigh/config.mjs

@@ -0,0 +1,131 @@
+// The shell configuration: where it is, the one transform `omakit weigh`
+// applies to it, and the backup it restores from. docs/WEIGH.md, "The
+// shell.json mutation", is the prose form of `without()` below; the two are
+// held together by tests/unit/weigh.test.mjs.
+//
+// The transform is pure and works on the effective configuration the shell
+// reports, not on the file. The file itself is touched in exactly two ways:
+// its bytes are read once and written to a timestamped backup beside it, and
+// those same bytes are written back over it on the way out. Nothing here
+// re-serialises what the user wrote.
+
+import { createHash } from "node:crypto"
+import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+/** Where Omarchy keeps the shell configuration: `~/.config/omarchy/shell.json`, the path the shell itself reads. */
+export function configPaths(env = process.env) {
+  const dir = join(env.HOME || "", ".config/omarchy")
+  return { dir, file: join(dir, "shell.json") }
+}
+
+/** The md5 of a buffer, as hex: what is printed before and after, and compared. */
+export function md5(bytes) {
+  return createHash("md5").update(bytes).digest("hex")
+}
+
+/**
+ * The effective configuration with a set of plugin ids removed: every bar
+ * layout entry with that id, every `plugins[]` entry with that id, and for
+ * a first-party id an entry in `disabledPlugins[]`, because a first-party
+ * plugin is enabled unless listed there. Nothing else in the document
+ * changes, and the input is not mutated.
+ *
+ * @param {object} config the effective configuration, `listShellConfig`
+ * @param {string[]} ids
+ * @param {{ id: string, firstParty?: boolean }[]} installed
+ */
+export function without(config, ids, installed) {
+  const remove = new Set(ids)
+  const firstParty = new Set(installed.filter((plugin) => plugin.firstParty).map((plugin) => plugin.id))
+  const out = structuredClone(config)
+  const idOf = (entry) => (entry && typeof entry === "object" ? entry.id : entry)
+  if (out.bar && out.bar.layout && typeof out.bar.layout === "object") {
+    for (const section of Object.keys(out.bar.layout)) {
+      if (Array.isArray(out.bar.layout[section])) {
+        out.bar.layout[section] = out.bar.layout[section].filter((entry) => !remove.has(idOf(entry)))
+      }
+    }
+  }
+  if (Array.isArray(out.plugins)) out.plugins = out.plugins.filter((entry) => !remove.has(idOf(entry)))
+  const disabled = new Set(Array.isArray(out.disabledPlugins) ? out.disabledPlugins : [])
+  for (const id of ids) if (firstParty.has(id)) disabled.add(id)
+  if (disabled.size) out.disabledPlugins = [...disabled].sort()
+  else delete out.disabledPlugins
+  return out
+}
+
+/**
+ * Read the configuration file and write its bytes to a timestamped backup
+ * beside it. Returns what the restore needs: the bytes, the backup path and
+ * the md5. A missing file is recorded as such and restored by removal.
+ *
+ * @param {string} configFile
+ * @param {string} stamp UTC, `YYYYMMDDHHMMSS`
+ */
+export function backupConfig(configFile, stamp) {
+  let bytes = null
+  try {
+    bytes = readFileSync(configFile)
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error
+  }
+  const backupFile = `${configFile}.omakit-backup-${stamp}`
+  // The same mode as the original: shell.json is 0600 on an Omarchy install,
+  // and a copy of a private file is a private file.
+  if (bytes !== null) writeFileSync(backupFile, bytes, { mode: statSync(configFile).mode & 0o777 })
+  return { configFile, backupFile, bytes, md5Before: bytes === null ? null : md5(bytes) }
+}
+
+/**
+ * Write one configuration for a run. The document is serialised the way
+ * `jq .` would, two-space indented, so the shell reads exactly what the
+ * transform produced.
+ */
+export function writeConfig(configFile, config) {
+  writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`)
+}
+
+/**
+ * Put the user's bytes back. Verification is a separate step, after the
+ * shell has been restarted on them: a shell that rewrites the file as it
+ * starts is exactly what the md5 has to catch, so it is read after the
+ * restart and not before.
+ *
+ * @param {{ configFile: string, bytes: Buffer|null }} backup
+ */
+export function restoreConfig(backup) {
+  const { configFile, bytes } = backup
+  if (bytes === null) {
+    try {
+      unlinkSync(configFile)
+    } catch {
+      // It was not there before and is not there now.
+    }
+    return
+  }
+  writeFileSync(configFile, bytes)
+}
+
+/**
+ * Are the user's bytes back: the md5 of what is on disk now against the md5
+ * of the backup. The backup is removed only when they are equal; otherwise
+ * it stays and the caller says so.
+ *
+ * @param {{ configFile: string, backupFile: string, bytes: Buffer|null, md5Before: string|null }} backup
+ * @returns {{ md5After: string|null, restored: boolean, backupRemoved: boolean }}
+ */
+export function verifyRestore(backup) {
+  const { configFile, backupFile, bytes, md5Before } = backup
+  if (bytes === null) return { md5After: null, restored: !existsSync(configFile), backupRemoved: false }
+  let md5After = null
+  try {
+    md5After = md5(readFileSync(configFile))
+  } catch {
+    md5After = null
+  }
+  const restored = md5After === md5Before
+  if (restored) unlinkSync(backupFile)
+  return { md5After, restored, backupRemoved: restored }
+}
+

package/tools/weigh/confirm.mjs

@@ -0,0 +1,32 @@
+// The one question `omakit weigh` asks: may it restart the shell that many
+// times. Asked at a terminal only, on stderr so stdout stays the report;
+// anywhere else, a pipe, an agent, --json, the answer has to arrive as
+// --yes, and cli.mjs refuses with a usage error when it does not. Nothing
+// typed here is written anywhere.
+
+import { createInterface } from "node:readline"
+import { action, colourEnabled, styler } from "../marketplace/style.mjs"
+
+/**
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream, colour?: boolean, question: string }} options
+ * @returns {Promise<boolean>} true only for `y` or `yes`, in any case; the end of stdin is no
+ */
+export function askYes({ input = process.stdin, output = process.stderr, colour = colourEnabled(output), question }) {
+  const c = styler(colour)
+  return new Promise((resolve) => {
+    const rl = createInterface({ input, terminal: false })
+    let answered = false
+    const settle = (value) => {
+      if (answered) return
+      answered = true
+      rl.close()
+      resolve(value)
+    }
+    rl.on("line", (line) => settle(/^y(?:es)?$/i.test(line.trim())))
+    rl.on("close", () => {
+      if (!answered) output.write("\n")
+      settle(false)
+    })
+    output.write(`${action(`${question} [y/N]:`, c, { indent: 0 })[0]} `)
+  })
+}

package/tools/weigh/contract.mjs

@@ -0,0 +1,167 @@
+// The JSON contract of docs/WEIGH.md, executable. `validateWeighDocument()`
+// returns every way a document departs from it, as sentences, and an empty
+// list when it does not. tests/unit/weigh.test.mjs holds every produced
+// document to it, and the lab scenario runs it over the document a real
+// shell produced, so the prose and the code cannot drift apart unnoticed.
+//
+// Run as a program: `node tools/weigh/contract.mjs <document.json>` prints
+// the problems and exits 1 on any.
+
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { tickPercent, verdict as verdictOf } from "./stats.mjs"
+
+const VERDICTS = new Set(["within-noise", "above-noise", "unknown"])
+
+function isStats(value, at, problems) {
+  if (!value || typeof value !== "object") {
+    problems.push(`${at} is not a stats object`)
+    return
+  }
+  for (const key of ["median", "spread", "min", "max"]) {
+    if (!(key in value) || (value[key] !== null && typeof value[key] !== "number")) problems.push(`${at}.${key} is neither a number nor null`)
+  }
+  if (!Array.isArray(value.runs) || value.runs.some((run) => typeof run !== "number")) problems.push(`${at}.runs is not a list of numbers`)
+  if (Array.isArray(value.runs) && value.runs.length === 0 && value.median !== null) problems.push(`${at} has no runs but a median`)
+}
+
+function isSample(sample, at, problems) {
+  for (const key of ["label", "started", "ended"]) if (typeof sample[key] !== "string") problems.push(`${at}.${key} is not a string`)
+  for (const key of ["run", "shellPid", "readyAfterSeconds", "windowSeconds"]) if (typeof sample[key] !== "number") problems.push(`${at}.${key} is not a number`)
+  if ("configRewritten" in sample && sample.configRewritten !== null && typeof sample.configRewritten !== "boolean") problems.push(`${at}.configRewritten is neither a boolean nor null`)
+  const shell = sample.shell
+  if (!shell || typeof shell !== "object") {
+    problems.push(`${at}.shell is missing`)
+    return
+  }
+  for (const key of ["pssKb", "rssKb", "pssKbSettled", "rssKbSettled"]) if (shell[key] !== null && typeof shell[key] !== "number") problems.push(`${at}.shell.${key} is neither a number nor null`)
+  if (shell.memoryAt !== "window-end") problems.push(`${at}.shell.memoryAt is not "window-end"`)
+  if (!Array.isArray(shell.trace)) problems.push(`${at}.shell.trace is not a list`)
+  else for (const [index, point] of shell.trace.entries()) {
+    if (typeof point.t !== "number") problems.push(`${at}.shell.trace[${index}].t is not a number`)
+    for (const key of ["pssKb", "rssKb"]) if (point[key] !== null && typeof point[key] !== "number") problems.push(`${at}.shell.trace[${index}].${key} is neither a number nor null`)
+  }
+  for (const key of ["cpuTicksStart", "cpuTicksEnd", "cpuSeconds", "cpuPercent", "reapedChildTicksStart", "reapedChildTicksEnd", "reapedChildCpuSeconds", "reapedChildCpuPercent"]) {
+    if (typeof shell[key] !== "number") problems.push(`${at}.shell.${key} is not a number`)
+  }
+  if (!Array.isArray(sample.children)) {
+    problems.push(`${at}.children is not a list`)
+    return
+  }
+  for (const [index, child] of sample.children.entries()) {
+    for (const key of ["pid", "firstSeen", "lastSeen", "cpuFirst", "cpuLast", "rssLast", "samples"]) if (typeof child[key] !== "number") problems.push(`${at}.children[${index}].${key} is not a number`)
+    for (const key of ["comm", "arg0"]) if (typeof child[key] !== "string") problems.push(`${at}.children[${index}].${key} is not a string`)
+    if (typeof child.arg0 === "string" && child.arg0.length > 80) problems.push(`${at}.children[${index}].arg0 is longer than 80 characters`)
+    if ("key" in child) problems.push(`${at}.children[${index}] carries the full command line, which never reaches the file`)
+  }
+}
+
+/**
+ * @param {object} document
+ * @returns {string[]} problems; empty when the document follows the contract
+ */
+export function validateWeighDocument(document) {
+  const problems = []
+  if (!document || typeof document !== "object") return ["the document is not an object"]
+  if (typeof document.omakit !== "string") problems.push("omakit is not a string")
+  if (document.command !== "weigh") problems.push('command is not "weigh"')
+  for (const key of ["method", "started", "ended", "host", "out"]) if (typeof document[key] !== "string") problems.push(`${key} is not a string`)
+  if (!document.shell || typeof document.shell.version !== "string" || typeof document.shell.omarchyPath !== "string") problems.push("shell lacks version and omarchyPath")
+  const settings = document.settings || {}
+  for (const key of ["runs", "windowSeconds", "settleSeconds", "readyTimeoutSeconds", "sampleIntervalMs", "clockTicksPerSecond"]) {
+    if (typeof settings[key] !== "number") problems.push(`settings.${key} is not a number`)
+  }
+  const config = document.config || {}
+  for (const key of ["path", "backup"]) if (typeof config[key] !== "string") problems.push(`config.${key} is not a string`)
+  for (const key of ["md5Before", "md5After"]) if (config[key] !== null && !/^[0-9a-f]{32}$/.test(String(config[key]))) problems.push(`config.${key} is not an md5`)
+  if (typeof config.restored !== "boolean") problems.push("config.restored is not a boolean")
+  if (config.restored !== (config.md5After === config.md5Before)) problems.push("config.restored disagrees with the two md5s")
+  if (!Array.isArray(document.audited) || document.audited.some((id) => typeof id !== "string")) problems.push("audited is not a list of ids")
+  if (!Array.isArray(document.failedRuns)) problems.push("failedRuns is not a list")
+
+  const baseline = document.baseline
+  if (!baseline || typeof baseline !== "object") {
+    problems.push("baseline is missing")
+  } else {
+    if (!baseline.config || typeof baseline.config !== "object") problems.push("baseline.config is not the configuration the baseline ran with")
+    for (const key of ["pssMb", "rssMb", "pssMbSettled", "rssMbSettled", "cpuPercent", "childRssMb"]) isStats(baseline[key], `baseline.${key}`, problems)
+    if (!Array.isArray(baseline.runs)) problems.push("baseline.runs is not a list")
+    else for (const [index, sample] of baseline.runs.entries()) isSample(sample, `baseline.runs[${index}]`, problems)
+  }
+  const floor = document.noiseFloor
+  if (!floor || typeof floor !== "object") {
+    problems.push("noiseFloor is missing")
+  } else {
+    for (const key of ["pssMb", "rssMb", "pssMbSettled", "rssMbSettled", "cpuPercent"]) if (floor[key] !== null && typeof floor[key] !== "number") problems.push(`noiseFloor.${key} is neither a number nor null`)
+    if (typeof floor.origin !== "string") problems.push("noiseFloor.origin is not a string")
+    // The floor is the baseline spread over two or more runs, and null for
+    // fewer: one run has no spread, and a spread of zero would read as a
+    // floor everything clears.
+    const enough = Array.isArray(baseline?.runs) && baseline.runs.length >= 2
+    if (baseline?.pssMb && floor.pssMb !== (enough ? baseline.pssMb.spread : null)) problems.push(enough ? "noiseFloor.pssMb is not the baseline Pss spread" : "noiseFloor.pssMb is set from fewer than two baseline runs")
+    if (baseline?.cpuPercent && floor.cpuPercent !== (enough ? baseline.cpuPercent.spread : null)) problems.push(enough ? "noiseFloor.cpuPercent is not the baseline CPU spread" : "noiseFloor.cpuPercent is set from fewer than two baseline runs")
+  }
+
+  if (!Array.isArray(document.plugins)) {
+    problems.push("plugins is not a list")
+    return problems
+  }
+  if (Array.isArray(document.audited) && document.plugins.length !== document.audited.length) problems.push("plugins has a row count other than audited")
+  for (const [index, plugin] of document.plugins.entries()) {
+    const at = `plugins[${index}]`
+    for (const key of ["id", "name", "origin"]) if (typeof plugin[key] !== "string") problems.push(`${at}.${key} is not a string`)
+    if (!Array.isArray(plugin.kinds)) problems.push(`${at}.kinds is not a list`)
+    if (typeof plugin.firstParty !== "boolean") problems.push(`${at}.firstParty is not a boolean`)
+    if (typeof plugin.runsCompleted !== "number") problems.push(`${at}.runsCompleted is not a number`)
+    for (const key of ["shellPssMb", "shellRssMb", "shellPssMbSettled", "shellCpuPercent", "childRssMb", "childCpuPercent", "childSpawns", "unattributedChildren"]) isStats(plugin[key], `${at}.${key}`, problems)
+    if (!Array.isArray(plugin.unattributedCommands) || plugin.unattributedCommands.some((command) => typeof command !== "string" || command.length > 100)) problems.push(`${at}.unattributedCommands is not a list of short commands`)
+    for (const key of ["totalMb", "totalCpuPercent"]) if (plugin[key] !== null && typeof plugin[key] !== "number") problems.push(`${at}.${key} is neither a number nor null`)
+    const verdict = plugin.verdict || {}
+    for (const key of ["memory", "cpu"]) if (!VERDICTS.has(verdict[key])) problems.push(`${at}.verdict.${key} is not a verdict`)
+    if (typeof verdict.summary !== "string") problems.push(`${at}.verdict.summary is not a string`)
+    if (plugin.shellPssMb?.median !== undefined && floor?.pssMb !== undefined) {
+      const expected = verdictOf(plugin.shellPssMb.median, floor.pssMb)
+      if (verdict.memory !== expected) problems.push(`${at}.verdict.memory is ${verdict.memory}; the median and the floor say ${expected}`)
+    }
+    if (plugin.shellCpuPercent?.median !== undefined && floor?.cpuPercent !== undefined) {
+      const expected = verdictOf(plugin.shellCpuPercent.median, floor.cpuPercent, tickPercent(settings.clockTicksPerSecond, settings.windowSeconds))
+      if (verdict.cpu !== expected) problems.push(`${at}.verdict.cpu is ${verdict.cpu}; the median and the floor say ${expected}`)
+    }
+    const within = plugin.withinNoise || {}
+    for (const key of ["pss", "rss", "cpu", "ownPss", "ownCpu"]) if (within[key] !== null && typeof within[key] !== "boolean") problems.push(`${at}.withinNoise.${key} is neither a boolean nor null`)
+    for (const key of ["baselinePssSpreadMb", "baselineCpuSpreadPercent", "cpuTickPercent"]) if (within[key] !== null && typeof within[key] !== "number") problems.push(`${at}.withinNoise.${key} is neither a number nor null`)
+    if (typeof within.note !== "string") problems.push(`${at}.withinNoise.note is not a string`)
+    if (plugin.readme !== null && typeof plugin.readme !== "string") problems.push(`${at}.readme is neither a string nor null`)
+    if (typeof plugin.readme === "string" && !/^Weighs (?:nothing measurable: no CPU above the floor \([\d.?]+%\) and no child process|(?:[\d.]+% CPU|no CPU above the floor \([\d.?]+%\)) and runs (?:no child process|\d+ child process(?:es)? using [\d.]+ MB and [\d.]+% CPU)), on Omarchy .+, measured with omakit weigh on \d{4}-\d{2}-\d{2}$/.test(plugin.readme)) {
+      problems.push(`${at}.readme is not the README sentence: ${plugin.readme}`)
+    }
+    if ((verdict.cpu === "unknown") !== (plugin.readme === null)) problems.push(`${at}.readme is ${plugin.readme === null ? "null with a verdict" : "present without one"}`)
+    if (typeof plugin.readme === "string" && /\bMB\b(?!.*child process)/.test(plugin.readme.split(" and runs ")[0])) problems.push(`${at}.readme speaks about the shell's memory`)
+    if (!Array.isArray(plugin.deltas)) {
+      problems.push(`${at}.deltas is not a list`)
+    } else {
+      if (plugin.deltas.length !== plugin.runsCompleted) problems.push(`${at}.deltas has ${plugin.deltas.length} entries for ${plugin.runsCompleted} completed runs`)
+      for (const [run, delta] of plugin.deltas.entries()) {
+        for (const key of ["run", "shellPssMb", "shellRssMb", "shellCpuPercent", "childRssMb", "childCpuPercent", "reapedChildCpuPercent", "childSpawns"]) {
+          if (typeof delta[key] !== "number") problems.push(`${at}.deltas[${run}].${key} is not a number`)
+        }
+        if (!Array.isArray(delta.children)) problems.push(`${at}.deltas[${run}].children is not a list`)
+        if (!Array.isArray(delta.unattributedChildren) || delta.unattributedChildren.some((child) => typeof child.comm !== "string" || typeof child.arg0 !== "string" || "key" in child)) problems.push(`${at}.deltas[${run}].unattributedChildren is not a list of {comm, arg0}`)
+      }
+    }
+    if (!Array.isArray(plugin.runs)) problems.push(`${at}.runs is not a list`)
+    else for (const [run, sample] of plugin.runs.entries()) isSample(sample, `${at}.runs[${run}]`, problems)
+  }
+  return problems
+}
+
+const invoked = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+if (invoked) {
+  const input = process.argv[2]
+  if (!input) throw new Error("usage: node tools/weigh/contract.mjs <document.json>")
+  const problems = validateWeighDocument(JSON.parse(readFileSync(resolve(input), "utf8")))
+  for (const problem of problems) process.stdout.write(`${problem}\n`)
+  process.stdout.write(problems.length ? `${problems.length} problem(s)\n` : "ok: the document follows the contract in docs/WEIGH.md\n")
+  process.exit(problems.length ? 1 : 0)
+}

package/tools/weigh/proc.mjs

@@ -0,0 +1,150 @@
+// Reading /proc, and nothing else. Every function takes the root of the
+// tree, `/proc` on a real machine and a directory of fixtures in
+// tests/unit/weigh.test.mjs, so the sampler is tested without a shell.
+//
+// What is read, and from where, is the origin every figure carries:
+//
+//   /proc/<pid>/stat          utime+stime (the shell's own CPU), cutime+cstime
+//                             (the CPU of every child it has reaped), ppid
+//   /proc/<pid>/status        VmRSS
+//   /proc/<pid>/smaps_rollup  Pss: a shared page counted once, divided among
+//                             the processes that share it
+//   /proc/<pid>/cmdline       the first argument, cut to 80 characters, and
+//                             the full line as a key that never leaves the run
+//
+// A process that disappears between the directory listing and the read is
+// skipped, not an error: a poller lives for milliseconds.
+
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+export const PROC = "/proc"
+
+/** How much of a child's first argument reaches the output: enough to tell `-m` from `status`, never a whole token. */
+export const ARG0_CHARS = 80
+
+/**
+ * The fields of /proc/<pid>/stat this tool reads, by their 1-based position
+ * in the man page: comm is field 2 and may contain spaces, so everything
+ * after its closing parenthesis is split on spaces and counted from field 3.
+ */
+function statOf(root, pid) {
+  let text
+  try {
+    text = readFileSync(join(root, String(pid), "stat"), "utf8")
+  } catch {
+    return null
+  }
+  const close = text.lastIndexOf(")")
+  const open = text.indexOf("(")
+  if (open < 0 || close < 0) return null
+  const rest = text.slice(close + 2).split(" ")
+  // rest[0] is field 3 (state); field n is rest[n - 3].
+  const field = (n) => Number(rest[n - 3])
+  return {
+    pid: Number(text.slice(0, open).trim()),
+    comm: text.slice(open + 1, close),
+    ppid: field(4),
+    utime: field(14),
+    stime: field(15),
+    cutime: field(16),
+    cstime: field(17),
+  }
+}
+
+/** utime + stime, in clock ticks, or null when the process is gone. */
+export function cpuTicks(root, pid) {
+  const stat = statOf(root, pid)
+  return stat ? stat.utime + stat.stime : null
+}
+
+/** cutime + cstime: the CPU of every child the process has reaped, in clock ticks. */
+export function childTicks(root, pid) {
+  const stat = statOf(root, pid)
+  return stat ? stat.cutime + stat.cstime : null
+}
+
+/** One `Key:   value kB` line out of status or smaps_rollup, in kB, or null. */
+function kbField(root, pid, file, key) {
+  let text
+  try {
+    text = readFileSync(join(root, String(pid), file), "utf8")
+  } catch {
+    return null
+  }
+  const match = text.match(new RegExp(`^${key}:\\s+(\\d+)\\s+kB`, "m"))
+  return match ? Number(match[1]) : null
+}
+
+/** VmRSS from /proc/<pid>/status, in kB. */
+export function rssKb(root, pid) {
+  return kbField(root, pid, "status", "VmRSS")
+}
+
+/** Pss from /proc/<pid>/smaps_rollup, in kB; null where the kernel does not offer the file. */
+export function pssKb(root, pid) {
+  return kbField(root, pid, "smaps_rollup", "Pss")
+}
+
+/** The first argument and the full command line of a process, from /proc/<pid>/cmdline. */
+function cmdlineOf(root, pid) {
+  let text
+  try {
+    text = readFileSync(join(root, String(pid), "cmdline"), "utf8")
+  } catch {
+    return { arg0: "", key: "" }
+  }
+  const parts = text.split("\0").filter((part, index, all) => index < all.length - 1 || part !== "")
+  return {
+    arg0: (parts[1] || "").slice(0, ARG0_CHARS).replace(/\t/g, " "),
+    key: parts.join(" ").replace(/\t/g, " "),
+  }
+}
+
+/**
+ * Every descendant of `rootPid`, one sample: pid, command name, first
+ * argument, the full command line as a key, CPU ticks and VmRSS. The key
+ * tells two `inotifywait -m` watchers apart during the run; it is used for
+ * attribution and never written to the output.
+ *
+ * @param {string} root
+ * @param {number} rootPid
+ * @returns {{ pid: number, comm: string, arg0: string, key: string, cpu: number, rss: number }[]}
+ */
+export function descendants(root, rootPid) {
+  const parent = new Map()
+  const name = new Map()
+  let entries
+  try {
+    entries = readdirSync(root)
+  } catch {
+    return []
+  }
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry)) continue
+    const stat = statOf(root, Number(entry))
+    if (!stat) continue
+    parent.set(stat.pid, stat.ppid)
+    name.set(stat.pid, stat.comm)
+  }
+  const out = []
+  for (const [pid] of parent) {
+    let up = parent.get(pid)
+    let depth = 0
+    while (up !== undefined && up !== 0 && up !== rootPid && depth < 32) {
+      up = parent.get(up)
+      depth += 1
+    }
+    if (up !== rootPid) continue
+    const { arg0, key } = cmdlineOf(root, pid)
+    out.push({
+      pid,
+      comm: name.get(pid),
+      arg0,
+      key: key || name.get(pid),
+      cpu: cpuTicks(root, pid) ?? 0,
+      rss: rssKb(root, pid) ?? 0,
+    })
+  }
+  return out.sort((a, b) => a.pid - b.pid)
+}