claude-code-runrate 0.1.0 → 0.2.1

package/src/launch-win.js

@@ -0,0 +1,457 @@
+// @ts-check
+'use strict';
+
+// src/launch-win.js — native-Windows launcher for `ccr` / `ccr <profile>`.
+//
+// Replaces the bash+tmux launch layer (scripts/launch.sh) on win32 by driving
+// Windows Terminal (wt.exe) split panes: pane 0 runs Claude Code, pane 1 runs
+// `ccr sidecar`, with CCR_STATE_DIR injected into both. See SPEC §4.2/§5.2.
+//
+// The pure, side-effect-free helpers (profile validation, state resolution,
+// wt.exe argv construction, the injected wt.exe lookup) are unit-tested without
+// spawning anything; run()/fallbackNoWt() drive the real side effects through
+// the injectable Deps in withDefaults().
+
+const path = require('node:path');
+const os = require('node:os');
+
+// Profile names land in filesystem paths and a spawned command, so allow only a
+// safe identifier — identical to the allow-list in scripts/launch.sh.
+const PROFILE_RE = /^[A-Za-z0-9._-]+$/;
+
+// Characters we cannot safely embed in the per-pane `cmd /k` payload, even with
+// every path wrapped in double quotes:
+//   "       ends the quoted string;
+//   %       triggers cmd.exe variable expansion (it fires even inside quotes);
+//   \r \n   break the command line.
+// By contrast & | < > ^ ( ) ARE literal inside the double quotes we wrap every
+// value in, so they need no special handling. The trust boundary here is the
+// user's own env/paths (self-injection, not RCE), so the goal is to turn a
+// silently-broken — or, with %, a maliciously-expandable — command into a clear,
+// actionable error rather than to defend against an attacker.
+const WT_UNSAFE_RE = /["%\r\n]/;
+
+/**
+ * @param {string} value
+ * @returns {boolean} true if `value` can be safely interpolated into the cmd /k payload
+ */
+function isWtArgSafe(value) {
+  return !WT_UNSAFE_RE.test(String(value));
+}
+
+// Upstream default split: the sidecar gets ~34% of the width.
+const DEFAULT_SIDEBAR_PCT = 34;
+
+// Where the sidecar pane sits relative to Claude. 'right' is a vertical split
+// (wt split-pane -V, the default — matches the width-based sizing above);
+// 'bottom' is a horizontal split (-H). Set via CCR_SIDEBAR_SIDE.
+const DEFAULT_SIDEBAR_SIDE = 'right';
+
+/**
+ * Map a sidebar side ('right' | 'bottom') to the wt.exe split-pane flag.
+ * 'right' → '-V' (new pane to the right), 'bottom' → '-H' (new pane below).
+ * Anything unrecognized falls back to the default side.
+ *
+ * @param {string} [side]
+ * @returns {'-V'|'-H'}
+ */
+function sidebarSplitFlag(side) {
+  const s = String(side || DEFAULT_SIDEBAR_SIDE).toLowerCase();
+  return s === 'bottom' ? '-H' : '-V';
+}
+
+/**
+ * @param {unknown} profile
+ * @returns {boolean} true if the profile name is a safe identifier
+ */
+function validateProfile(profile) {
+  return typeof profile === 'string' && PROFILE_RE.test(profile);
+}
+
+/**
+ * Resolve the Claude command, tmux-equivalent session name, state dir, and (for
+ * profiles) the expected CCS instance dir. Mirrors scripts/launch.sh, honoring
+ * the CC_BIN / CCR_SESSION / CCR_STATE_DIR overrides.
+ *
+ * @param {string} [profile] CCS profile name, or undefined for plain `claude`
+ * @param {{ env?: NodeJS.ProcessEnv, home?: string }} [opts]
+ * @returns {{ ccCmd: string, session: string, stateDir: string,
+ *   instanceDir: string|null, usesCcs: boolean }}
+ */
+function resolveProfileState(profile, opts = {}) {
+  const env = opts.env || process.env;
+  const home = opts.home || os.homedir();
+
+  if (profile) {
+    return {
+      ccCmd: `ccs ${profile}`,
+      session: env.CCR_SESSION || `ccr-${profile}`,
+      stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', profile),
+      instanceDir: path.join(home, '.ccs', 'instances', profile),
+      usesCcs: true,
+    };
+  }
+  return {
+    ccCmd: env.CC_BIN || 'claude',
+    session: env.CCR_SESSION || 'ccr',
+    stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr'),
+    instanceDir: null,
+    usesCcs: false,
+  };
+}
+
+/**
+ * Convert a width percentage (e.g. 34) into the fraction string wt.exe's
+ * `split-pane -s` expects (e.g. "0.34"). Clamps to a sane 5..95 range.
+ *
+ * @param {number} [pct]
+ * @returns {string}
+ */
+function sidebarFraction(pct) {
+  let p = Number(pct);
+  if (!Number.isFinite(p)) p = DEFAULT_SIDEBAR_PCT;
+  p = Math.min(95, Math.max(5, Math.round(p)));
+  // Strip any float noise: 34 -> "0.34", 50 -> "0.5".
+  return String(Math.round(p) / 100);
+}
+
+/**
+ * Build the per-pane cmd.exe payload. Env is injected with `set "VAR=val"` so a
+ * path with spaces (or & | < >, which are literal inside the quotes) is fine and
+ * no trailing space is captured. Callers MUST pre-validate `stateDir` with
+ * isWtArgSafe — `"` and `%` are NOT made safe by these quotes (see WT_UNSAFE_RE).
+ *
+ * @param {string} stateDir
+ * @param {string} body the command(s) to run after the env is set
+ * @returns {string}
+ */
+function paneCommand(stateDir, body) {
+  return `set "CCR_STATE_DIR=${stateDir}"&& ${body}`;
+}
+
+/**
+ * Compute the column budget for the sidecar pane so it can clamp every line and
+ * never soft-wrap. `process.stdout.columns` inside the `cmd /c` conpty pane is
+ * unreliable (often undefined or the FULL window width, not the narrow split),
+ * so the launcher — whose own stdout DOES report the live terminal width —
+ * computes the pane width here and injects it as CCR_SIDECAR_COLS.
+ *
+ * A vertical split (-V, sidebar on the right) gets `frac` of the width, minus one
+ * column for the pane divider. A horizontal split (-H, sidebar on the bottom)
+ * keeps the full width. Returns null when the terminal width is unknown (non-TTY
+ * launch) — the sidecar then falls back to whatever it can detect.
+ *
+ * @param {number|undefined} termCols the launcher's own terminal width
+ * @param {number} fracNum the sidebar fraction (e.g. 0.34)
+ * @param {'-V'|'-H'} splitFlag
+ * @returns {number|null}
+ */
+function sidecarCols(termCols, fracNum, splitFlag) {
+  const t = Number(termCols);
+  if (!Number.isFinite(t) || t <= 0) return null;
+  if (splitFlag === '-H') return Math.max(20, Math.floor(t)); // bottom split keeps full width
+  return Math.max(20, Math.floor(t * fracNum) - 1);            // right split: fraction, less the divider
+}
+
+/**
+ * Build the argv passed to wt.exe (excluding the wt.exe path itself):
+ *   -w 0 new-tab --title Claude cmd /c "<pane0>" ; split-pane -H -s <frac> cmd /c "<pane1>"
+ *
+ * `-w 0` targets the CURRENT Windows Terminal window (open a tab in the window
+ * you ran `ccr` from) instead of spawning a separate window. The ";" pane
+ * separator is its own argv token (wt re-parses it); per-pane env is injected via
+ * `cmd /c set ...` rather than wt global env.
+ *
+ * Teardown mirrors the tmux launcher's sweep (launch.sh: `… ; touch exited; …;
+ * kill-session`): both panes run under `cmd /c`, so each closes when its command
+ * ends. On Claude exit pane 0 drops the `exited` sentinel and deletes the temp
+ * settings file; the sidecar runs with `--exit-on-end` so it detects the exit
+ * within ~120ms and closes pane 1 after a ~200ms grace (see sidecar.run).
+ *
+ * Close ORDER drives the sweep: pane 0 then lingers (SWEEP_LINGER ≈ 1s) past the
+ * sidecar's ~320ms close so the RIGHT pane collapses FIRST and Claude expands
+ * rightward to fill it — the sidebar border sweeps left→right and the tab folds,
+ * instead of pane 0 vanishing first and the sidecar ballooning right→left.
+ *
+ * Throws if any interpolated value contains a character that would break (or, in
+ * the case of %, hijack) the cmd /c payload — see isWtArgSafe. run() catches
+ * this and reports a clean error instead of spawning a broken command.
+ *
+ * @param {{ ccCmd: string, settingsFile: string, stateDir: string,
+ *   node: string, ccrJs: string, sidebarPct?: number, sidebarSide?: string,
+ *   termCols?: number }} o
+ * @returns {string[]}
+ */
+function buildWtArgs(o) {
+  const { ccCmd, settingsFile, stateDir, node, ccrJs } = o;
+  for (const [label, value] of [
+    ['profile/state dir', stateDir],
+    ['settings file path', settingsFile],
+    ['claude command', ccCmd],
+    ['node path', node],
+    ['ccr.js path', ccrJs],
+  ]) {
+    if (!isWtArgSafe(value)) {
+      throw new Error(
+        `cannot launch: ${label} contains an unsupported character (" or %) for the ` +
+        `Windows Terminal launcher: ${value}`,
+      );
+    }
+  }
+  const frac = sidebarFraction(o.sidebarPct);
+  const splitFlag = sidebarSplitFlag(o.sidebarSide);
+  const exited = path.win32.join(stateDir, 'exited');
+
+  // After Claude exits we drop the sentinel + clean the settings file, then idle
+  // ~1s so pane 1 (which now detects the exit within ~120ms and closes after a
+  // ~200ms grace) folds FIRST and the border sweeps left→right. `ping -n 2`
+  // loopback is a reliable ~1s — its fixed inter-ping gap can't undershoot the
+  // sidecar's close the way `timeout /t 1` (0–1s, second-aligned) could, and it
+  // has none of `timeout`'s stdin quirks. ~1s is the floor: cmd.exe's wait
+  // primitives have 1-second granularity, so a tighter robust delay isn't
+  // available without fragile tricks. Silent under `>nul`.
+  const SWEEP_LINGER = 'ping -n 2 127.0.0.1 >nul';
+  const pane0 = paneCommand(
+    stateDir,
+    `${ccCmd} --settings "${settingsFile}" & type nul > "${exited}" & del /q "${settingsFile}" & ${SWEEP_LINGER}`,
+  );
+  // Inject the computed pane width so the sidecar clamps cleanly even when its own
+  // process.stdout.columns is unreliable inside the cmd /c conpty pane.
+  const cols = sidecarCols(o.termCols, Number(frac), splitFlag);
+  const sidecarBody =
+    (cols != null ? `set "CCR_SIDECAR_COLS=${cols}"&& ` : '') +
+    `"${node}" "${ccrJs}" sidecar --exit-on-end`;
+  const pane1 = paneCommand(stateDir, sidecarBody);
+
+  return [
+    '-w', '0', 'new-tab', '--title', 'Claude', 'cmd', '/c', pane0,
+    ';',
+    'split-pane', splitFlag, '-s', frac, 'cmd', '/c', pane1,
+  ];
+}
+
+/**
+ * Resolve wt.exe via `where`, or return null if absent. The lookup is injected
+ * so this stays unit-testable; the default shells out to `where`.
+ *
+ * @param {{ runWhere?: (name: string) => (string|null) }} [opts]
+ * @returns {string|null}
+ */
+function findWindowsTerminal(opts = {}) {
+  const lookup = opts.runWhere || defaultWhere;
+  return lookup('wt') || lookup('wt.exe') || null;
+}
+
+/**
+ * @param {string} name
+ * @returns {string|null} first match path, or null
+ */
+function defaultWhere(name) {
+  const { spawnSync } = require('node:child_process');
+  const r = spawnSync('where', [name], { encoding: 'utf8' });
+  if (r.status !== 0 || !r.stdout) return null;
+  const first = r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
+  return first || null;
+}
+
+const inject = require('./settings-inject');
+const { ensureSecureDir } = require('./state-dir');
+
+/**
+ * Fill in real-environment implementations for anything the caller didn't
+ * inject. Every external effect (PATH lookups, fs, spawn, output) flows through
+ * here so run() can be unit-tested with pure stand-ins.
+ *
+ * @param {Partial<Deps>} deps
+ * @returns {Deps}
+ */
+function withDefaults(deps) {
+  const env = deps.env || process.env;
+  const home = deps.home || os.homedir();
+  return {
+    env,
+    home,
+    // The launcher's own stdout reports the live terminal width — the sidecar's
+    // does not, inside its cmd /c pane (see sidecarCols). undefined on non-TTY.
+    cols: deps.cols != null ? deps.cols : process.stdout.columns,
+    node: deps.node || process.execPath,
+    ccrJs: deps.ccrJs || path.join(__dirname, '..', 'bin', 'ccr.js'),
+    out: deps.out || ((s) => { process.stdout.write(s); }),
+    err: deps.err || ((s) => { process.stderr.write(s); }),
+    findWt: deps.findWt || (() => findWindowsTerminal()),
+    which: deps.which || defaultWhere,
+    existsDir: deps.existsDir || defaultExistsDir,
+    listDir: deps.listDir || defaultListDir,
+    ensureDir: deps.ensureDir || ensureSecureDir,
+    removeExited: deps.removeExited || defaultRemoveExited,
+    writeSettings: deps.writeSettings || ((s) => inject.writeSettingsFile(s)),
+    cleanup: deps.cleanup || ((f) => inject.cleanupSettingsFile(f)),
+    spawnWt: deps.spawnWt || defaultSpawnWt,
+  };
+}
+
+/** @param {string} dir @returns {boolean} */
+function defaultExistsDir(dir) {
+  try {
+    return require('node:fs').statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** @param {string} dir @returns {string[]} */
+function defaultListDir(dir) {
+  try {
+    return require('node:fs').readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** @param {string} stateDir @returns {void} */
+function defaultRemoveExited(stateDir) {
+  try {
+    require('node:fs').rmSync(path.join(stateDir, 'exited'), { force: true });
+  } catch {
+    // best effort
+  }
+}
+
+/** @param {string} wt @param {string[]} args @returns {{status:number|null, error?:Error}} */
+function defaultSpawnWt(wt, args) {
+  return require('node:child_process').spawnSync(wt, args, { stdio: 'ignore' });
+}
+
+/**
+ * The graceful no-Windows-Terminal fallback: keep the working native CLI usable
+ * instead of dead-ending. Returns 1 (no crash, no stack trace). SPEC §6 / §8.7.
+ *
+ * @param {{ err: (s: string) => void }} d
+ * @returns {number}
+ */
+function fallbackNoWt(d) {
+  d.err(
+    'ccr: Windows Terminal (wt.exe) not found — it hosts the live sidecar.\n' +
+    '     Install it:  winget install Microsoft.WindowsTerminal\n' +
+    '     Until then these native commands work without it:\n' +
+    '       ccr economy      one-off economy panel\n' +
+    "       ccr statusline   wire into Claude Code's statusLine\n" +
+    '       ccr doctor       check your setup\n');
+  return 1;
+}
+
+/**
+ * `ccr [profile]` on native Windows: split a Windows Terminal window into
+ * Claude Code + ccr sidecar. Implements SPEC §4.2 steps 1–7. Returns an exit
+ * code. All side effects are injectable for testing (see withDefaults).
+ *
+ * @param {string} [profile]
+ * @param {Partial<Deps>} [deps]
+ * @returns {number}
+ */
+function run(profile, deps = {}) {
+  const d = withDefaults(deps);
+
+  // 1. Validate the profile (it lands in paths and a spawned command).
+  if (profile !== undefined && !validateProfile(profile)) {
+    d.err(`ccr: invalid profile name '${profile}' (allowed: letters, digits, . _ -)\n`);
+    return 1;
+  }
+
+  // 2. Require Windows Terminal, else fall back gracefully.
+  const wt = d.findWt();
+  if (!wt) return fallbackNoWt(d);
+
+  // 3. Resolve profile state + required binaries.
+  const st = resolveProfileState(profile, { env: d.env, home: d.home });
+  if (st.usesCcs) {
+    if (!d.which('ccs')) {
+      d.err("ccr: 'ccs' not found on PATH — pass a profile only if CCS is installed.\n");
+      return 1;
+    }
+    if (st.instanceDir && !d.existsDir(st.instanceDir)) {
+      d.err(`ccr: CCS profile '${profile}' not found (${st.instanceDir}).\n`);
+      const avail = d.listDir(path.join(d.home, '.ccs', 'instances')).join(' ');
+      d.err(`     available: ${avail}\n`);
+      return 1;
+    }
+  } else {
+    const bin = st.ccCmd.split(' ')[0];
+    if (!d.which(bin)) {
+      d.err(`ccr: '${bin}' not found on PATH.\n`);
+      return 1;
+    }
+  }
+
+  // 4. Prepare the per-profile state dir; clear a stale sentinel.
+  try { d.ensureDir(st.stateDir); } catch { /* best effort */ }
+  d.removeExited(st.stateDir);
+
+  // 5. Inject statusLine via a temp settings FILE (avoids CLI JSON quoting).
+  const command = inject.buildStatusLineCommandInline({ node: d.node, ccrJs: d.ccrJs });
+  const settingsFile = d.writeSettings(inject.buildSettings(command));
+
+  // 6. Build + spawn the wt.exe command (CCR_STATE_DIR injected per-pane).
+  const pct = parseInt(String(d.env.CCR_SIDEBAR_PCT), 10);
+  let args;
+  try {
+    args = buildWtArgs({
+      ccCmd: st.ccCmd,
+      settingsFile,
+      stateDir: st.stateDir,
+      node: d.node,
+      ccrJs: d.ccrJs,
+      sidebarPct: Number.isFinite(pct) ? pct : DEFAULT_SIDEBAR_PCT,
+      sidebarSide: d.env.CCR_SIDEBAR_SIDE || DEFAULT_SIDEBAR_SIDE,
+      termCols: d.cols,
+    });
+  } catch (e) {
+    d.err(`ccr: ${e instanceof Error ? e.message : String(e)}\n`);
+    d.cleanup(settingsFile); // window never opened → nothing else will clean up
+    return 1;
+  }
+  const r = d.spawnWt(wt, args);
+  if (r.error) {
+    d.err(`ccr: failed to launch Windows Terminal: ${r.error.message}\n`);
+    d.cleanup(settingsFile); // window never opened → pane 0 can't clean up
+    return 1;
+  }
+  // 7. On success the settings file is cleaned up by pane 0 when Claude exits.
+  return typeof r.status === 'number' ? r.status : 0;
+}
+
+/**
+ * @typedef {object} Deps
+ * @property {NodeJS.ProcessEnv} env
+ * @property {string} home
+ * @property {number|undefined} cols
+ * @property {string} node
+ * @property {string} ccrJs
+ * @property {(s: string) => void} out
+ * @property {(s: string) => void} err
+ * @property {() => (string|null)} findWt
+ * @property {(name: string) => (string|null)} which
+ * @property {(dir: string) => boolean} existsDir
+ * @property {(dir: string) => string[]} listDir
+ * @property {(dir: string) => void} ensureDir
+ * @property {(dir: string) => void} removeExited
+ * @property {(settings: object) => string} writeSettings
+ * @property {(file: string) => void} cleanup
+ * @property {(wt: string, args: string[]) => {status: number|null, error?: Error}} spawnWt
+ */
+
+module.exports = {
+  PROFILE_RE,
+  DEFAULT_SIDEBAR_PCT,
+  DEFAULT_SIDEBAR_SIDE,
+  validateProfile,
+  isWtArgSafe,
+  resolveProfileState,
+  sidebarFraction,
+  sidebarSplitFlag,
+  sidecarCols,
+  buildWtArgs,
+  findWindowsTerminal,
+  run,
+  fallbackNoWt,
+};

package/src/render/economy.js

@@ -15,7 +15,11 @@ const { dim, bold, green, red, yellow, cyan, flash, pctColor, bar, tok, fmtMins,
 const bandColor = { imminent: red, warn: yellow, ok: cyan };
 
 function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolean} */ tick, /** @type {number} */ labelW) {
-  const used = Math.round(row.est.usedPct);
+  // Truncate, don't round: Claude's own surfaces (`/usage`, claude.ai usage)
+  // floor the fractional `used_percentage` (e.g. 41.6 → "41%"). Math.round here
+  // read ~1pt high on values past the half-point. Display only — the burn/ROI
+  // math below still uses the raw fractional `row.est.usedPct`.
+  const used = Math.floor(row.est.usedPct);
   const ml = row.est.minutesLeft;
   const b = band(ml);
   // Per-row colour dot: green when the window resets before you'd hit it,

package/src/render/shared.js

@@ -21,6 +21,34 @@ function bar(/** @type {number} */ p, w = 10) {
   return '▓'.repeat(f) + '░'.repeat(w - f);
 }
 
+/**
+ * Clamp one line to `cols` visible columns: SGR escapes (`\x1b[…m`) pass through
+ * with zero width, printable chars count as 1. Appends a reset if it had to cut,
+ * so a severed colour run doesn't bleed into the cleared tail. Prevents the soft
+ * wrap that corrupts the sidecar's cursor-home redraw in a narrow pane. A
+ * non-positive `cols` (e.g. a non-TTY where columns is undefined) is a no-op.
+ * @param {string} line
+ * @param {number} [cols]
+ * @returns {string}
+ */
+function clampVisible(line, cols) {
+  if (!(typeof cols === 'number' && cols > 0)) return line;
+  const sgr = /\x1b\[[0-9;]*m/y;
+  let out = '';
+  let width = 0;
+  let i = 0;
+  while (i < line.length) {
+    sgr.lastIndex = i;
+    const m = sgr.exec(line);
+    if (m) { out += m[0]; i = sgr.lastIndex; continue; }
+    if (width >= cols) return out + '\x1b[0m';
+    out += line[i];
+    width += 1;
+    i += 1;
+  }
+  return out;
+}
+
 function tok(/** @type {number|null} */ n) {
   if (n == null) return '?';
   if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
@@ -46,4 +74,4 @@ function fmtReset(/** @type {number|null} */ min) {
   return `${m}m`;
 }
 
-module.exports = { e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, tok, fmtMins, fmtReset };
+module.exports = { e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, clampVisible, tok, fmtMins, fmtReset };

package/src/settings-inject.js

@@ -0,0 +1,77 @@
+// @ts-check
+'use strict';
+
+// src/settings-inject.js — per-launch statusLine injection (SPEC §4.2 step 5, §5.3).
+//
+// Claude Code must call `ccr statusline` on every status tick WITHOUT mutating
+// any file under ~/.claude. We achieve that exactly like upstream launch.sh:
+// write a throwaway settings object to a temp file and pass it to
+// `claude --settings <file>`. A FILE (not inline --settings '{...}') sidesteps
+// the Windows command-line JSON-quoting minefield.
+//
+// The statusLine `command` value is the inline form: node + bin/ccr.js resolved
+// by absolute path. Because it lives inside the JSON settings file (never on a
+// shell line), no shell-quoting is involved and no separate shim file is needed.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+/**
+ * Inline statusLine command: resolve node + ccr.js by path. Quoting is safe
+ * because this value lives inside the JSON settings FILE, not on a shell line.
+ *
+ * @param {{ node: string, ccrJs: string }} o
+ * @returns {string}
+ */
+function buildStatusLineCommandInline(o) {
+  return `"${o.node}" "${o.ccrJs}" statusline`;
+}
+
+/**
+ * The settings object Claude Code consumes via --settings.
+ *
+ * @param {string} command the statusLine command value
+ * @returns {{ statusLine: { type: 'command', command: string } }}
+ */
+function buildSettings(command) {
+  return { statusLine: { type: 'command', command } };
+}
+
+/**
+ * Write the settings object to a uniquely-named temp file and return its path.
+ * The file lives under the temp dir only — never under ~/.claude.
+ *
+ * @param {object} settings
+ * @param {{ tmpDir?: string, rand?: string }} [opts]
+ * @returns {string} absolute path to the written settings file
+ */
+function writeSettingsFile(settings, opts = {}) {
+  const dir = opts.tmpDir || os.tmpdir();
+  const rand = opts.rand || crypto.randomBytes(4).toString('hex');
+  const file = path.join(dir, `ccr-settings-${rand}.json`);
+  fs.writeFileSync(file, JSON.stringify(settings), { encoding: 'utf8' });
+  return file;
+}
+
+/**
+ * Best-effort removal of the temp settings file. Never throws.
+ *
+ * @param {string} file
+ * @returns {void}
+ */
+function cleanupSettingsFile(file) {
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    // best-effort: a leftover temp file is harmless.
+  }
+}
+
+module.exports = {
+  buildStatusLineCommandInline,
+  buildSettings,
+  writeSettingsFile,
+  cleanupSettingsFile,
+};