@litfamily/lithermes 1.0.18 → 1.0.19

package/src/cli.js

@@ -1,11 +1,11 @@
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
 const readline = require("node:readline");
-const { installLitHermes, previewModelRoute, uninstallLitHermes } = require("./lib/install");
+const { installLitHermes, previewModelRoute, previewUninstall, uninstallLitHermes } = require("./lib/install");
 const { promptModelRouteSession, renderInstallBanner, routeFromConfig } = require("./lib/modelPrompt");
 const { checkLitHermes, doctorLitHermes } = require("./lib/check");
 const { createSpinner, renderInstallReceipt, shouldUseSpinner } = require("./lib/spinner");
-const { listHud, applyHud, clearHud, promptAccent, resolveHome } = require("./lib/hud");
+const { listHud, applyHud, clearHud, previewClearHud, previewHud, promptAccent, resolveHome } = require("./lib/hud");
 const { supportsColor, findAccent, skinName } = require("./lib/skins");
 const {
   readConfig,
@@ -22,29 +22,145 @@ const {
   shouldAutoUpdate,
 } = require("./lib/updateNotifier");
 
+// Every option the CLI understands. A flag is a boolean switch unless it is listed in VALUE_FLAGS.
+const VALUE_FLAGS = new Set([
+  "hermes-home", "hermes-repo", "provider", "model", "effort", "child-provider", "child-model", "child-effort",
+  "hud", "style", "installed-version",
+]);
+
+// What each command accepts, and how help shows it. A command refuses anything not listed here.
+const HOME = { "hermes-home": "PATH" };
+const COMMAND_SPECS = {
+  install: {
+    usage: "install",
+    positionals: [0, 0],
+    flags: {
+      yes: "", "dry-run": "", offline: "", json: "", force: "", "reconfigure-model": "",
+      provider: "ID", model: "ID", effort: "LEVEL", "child-provider": "ID", "child-model": "ID", "child-effort": "LEVEL",
+      spinner: "", "no-spinner": "", hud: "<accent>", "no-hud": "", style: "ID", "no-style": "",
+      "patch-installed-hermes": "", "no-patch-installed-hermes": "", "no-auto-update": "", ...HOME, "hermes-repo": "PATH",
+    },
+  },
+  check: {
+    usage: "check",
+    positionals: [0, 0],
+    flags: { offline: "", "gateway-offline": "", json: "", "no-auto-update": "", ...HOME, "hermes-repo": "PATH" },
+  },
+  doctor: {
+    usage: "doctor",
+    positionals: [0, 0],
+    flags: { offline: "", json: "", "no-auto-update": "", ...HOME, "hermes-repo": "PATH" },
+  },
+  "motion-runtime": {
+    usage: "motion-runtime install|status",
+    positionals: [1, 1],
+    actions: ["install", "status"],
+    flags: { "dry-run": "", audio: "", "word-timing": "", ...HOME },
+    note: "Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit ca251e3.",
+  },
+  uninstall: {
+    usage: "uninstall",
+    positionals: [0, 0],
+    flags: { yes: "", "dry-run": "", "rollback-patches": "", offline: "", "no-auto-update": "", ...HOME, "hermes-repo": "PATH" },
+  },
+  hud: {
+    usage: "hud [<accent>|off]",
+    positionals: [0, 1],
+    flags: { list: "", "dry-run": "", ...HOME },
+    note: "(Hermes HUD skin accents)",
+  },
+  version: { usage: "version", positionals: [0, 0], flags: {} },
+  help: { usage: "help", positionals: [0, 1], flags: {}, hidden: true },
+  // Private bridge for the installed plugin's automatic update; deliberately absent from help.
+  "__auto-update": { usage: "__auto-update", positionals: [0, 0], flags: { ...HOME, "installed-version": "VERSION" }, hidden: true },
+};
+
+const COMMAND_ALIASES = { "--version": "version", "-v": "version", "--help": "help", "-h": "help" };
+
+class UsageError extends Error {
+  constructor(message) {
+    super(`${message}\nRun \`lithermes help\` for the options each command accepts.`);
+    this.exitCode = 2;
+  }
+}
+
 function parseArgs(argv) {
   const flags = {};
   const positionals = [];
+  const problems = [];
+  let helpRequested = false;
   for (let i = 0; i < argv.length; i += 1) {
     const item = argv[i];
-    if (!item.startsWith("--")) {
+    if (positionals.length === 0 && COMMAND_ALIASES[item]) {
+      positionals.push(COMMAND_ALIASES[item]);
+      continue;
+    }
+    if (item === "--help" || item === "-h") {
+      helpRequested = true;
+      continue;
+    }
+    if (!item.startsWith("-") || item === "-") {
       positionals.push(item);
       continue;
     }
-    const key = item.slice(2);
-    if (["yes", "offline", "json", "dry-run", "spinner", "no-spinner", "gateway-offline", "force", "patch-installed-hermes", "no-patch-installed-hermes", "rollback-patches", "list", "no-hud", "no-style", "no-auto-update", "reconfigure-model", "audio", "word-timing"].includes(key)) {
-      flags[key] = true;
+    if (!item.startsWith("--")) {
+      problems.push(`unknown option '${item}'`);
       continue;
     }
-    const value = argv[i + 1];
-    if (!value || value.startsWith("--")) {
-      flags[key] = "";
+    const equals = item.indexOf("=");
+    const key = equals === -1 ? item.slice(2) : item.slice(2, equals);
+    const inline = equals === -1 ? undefined : item.slice(equals + 1);
+    if (VALUE_FLAGS.has(key)) {
+      const value = inline ?? argv[i + 1];
+      if (value === undefined || value === "" || (inline === undefined && value.startsWith("-"))) {
+        problems.push(`option '--${key}' needs a value`);
+        continue;
+      }
+      flags[key] = value;
+      if (inline === undefined) i += 1;
       continue;
     }
-    flags[key] = value;
-    i += 1;
+    if (inline === undefined || inline === "true") flags[key] = true;
+    else if (inline !== "false") problems.push(`option '--${key}' expects true or false, not '${inline}'`);
   }
-  return { command: positionals[0] || "help", flags, positionals };
+  return { command: positionals[0] || "help", flags, positionals, problems, helpRequested };
+}
+
+// Refuse before anything runs: unknown options, options another command owns, and stray words.
+function validateArgs({ command, flags, positionals, problems }) {
+  const spec = COMMAND_SPECS[command];
+  if (!spec) throw new UsageError(`lithermes: unknown command '${command}'.`);
+  const issues = [...problems];
+  for (const key of Object.keys(flags)) {
+    if (!Object.prototype.hasOwnProperty.call(spec.flags, key)) issues.push(`unknown option '--${key}'`);
+  }
+  const extra = positionals.slice(1);
+  const [min, max] = spec.positionals;
+  if (extra.length > max) issues.push(`unexpected argument '${extra[max]}'`);
+  else if (extra.length < min) issues.push(spec.actions ? `missing action (${spec.actions.join(" or ")})` : "missing argument");
+  else if (spec.actions && !spec.actions.includes(extra[0])) issues.push(`unexpected argument '${extra[0]}' (expected ${spec.actions.join(" or ")})`);
+  if (issues.length) throw new UsageError(`lithermes ${command}: ${issues.join("; ")}.`);
+}
+
+function helpText() {
+  const lines = ["lithermes commands:"];
+  for (const spec of Object.values(COMMAND_SPECS)) {
+    if (spec.hidden) continue;
+    const options = Object.entries(spec.flags).map(([key, value]) => `[--${key}${value ? ` ${value}` : ""}]`);
+    const rows = [];
+    let row = `  ${spec.usage}`;
+    for (const option of options) {
+      if (row.length + option.length + 1 > 100) {
+        rows.push(row);
+        row = `${" ".repeat(spec.usage.length + 2)} ${option}`;
+      } else row += ` ${option}`;
+    }
+    rows.push(spec.note && row.length + spec.note.length < 100 && !spec.note.includes("MIT") ? `${row}   ${spec.note}` : row);
+    if (spec.note && spec.note.includes("MIT")) rows.push(`  ${spec.note}`);
+    lines.push(...rows);
+  }
+  lines.push("  --dry-run (or --dry-run=true) shows what a command would change and changes nothing; --dry-run=false runs it normally.");
+  return lines.join("\n");
 }
 
 function packageVersion() {
@@ -67,6 +183,27 @@ function motionRuntime(action, flags = {}) {
   };
 }
 
+// Dry run of `motion-runtime install`: the runtime module only reads its pins and the cache here.
+async function motionRuntimePlan(flags = {}) {
+  const { pathToFileURL } = require("node:url");
+  const script = path.join(__dirname, "..", "assets", "lithermes-plugin", "skills", "lit-typographic-motion", "bin", "runtime.mjs");
+  const runtime = await import(pathToFileURL(script).href);
+  const env = { ...process.env, HERMES_HOME: resolveHome(flags) };
+  const ready = runtime.findCache(env);
+  const fonts = runtime.fontState(env);
+  const lines = ["DRY RUN: would install the motion runtime", `cache: ${ready || runtime.cacheRoots(env)[0]}`];
+  if (flags["word-timing"]) lines.push(`word-timing: would be refused (fail-closed): ${runtime.wordTimingPlan().reason}`);
+  else if (ready && fonts.ok) lines.push("node packages and fonts: already READY; nothing to install");
+  else lines.push(`would run npm ci for the pinned node packages and fetch ${runtime.FONT_PINS.length} pinned fonts`);
+  if (flags.audio && !flags["word-timing"]) {
+    lines.push(runtime.audioState(env).state === "ready"
+      ? "audio venv: already READY"
+      : "would create the audio venv and pip-install the hash-pinned requirements.lock");
+  }
+  lines.push("Nothing was downloaded or written.");
+  return lines.join("\n");
+}
+
 function printCommandBanner(command, flags, runtime = {}) {
   // Keep machine-oriented routes byte-stable: their stdout is consumed as a
   // version line or JSON receipt rather than a human-facing command report.
@@ -269,9 +406,15 @@ async function maybePickHudAccent(flags, runtime = {}, { promptForAccent = false
 }
 
 async function main(argv, runtime = {}) {
-  const { command, flags, positionals } = parseArgs(argv);
+  const parsed = parseArgs(argv);
+  const { command, flags, positionals } = parsed;
+  if (parsed.helpRequested) {
+    console.log(helpText());
+    return;
+  }
+  validateArgs(parsed);
   printCommandBanner(command, flags, runtime);
-  if (command === "version" || command === "--version" || command === "-v") {
+  if (command === "version") {
     console.log(packageVersion());
     return;
   }
@@ -282,11 +425,11 @@ async function main(argv, runtime = {}) {
       return;
     }
     if (accent === "off" || accent === "clear" || accent === "none") {
-      console.log(clearHud(flags));
+      console.log(flags["dry-run"] ? previewClearHud(flags) : clearHud(flags));
       return;
     }
     try {
-      console.log(applyHud(accent, flags));
+      console.log(flags["dry-run"] ? previewHud(accent, flags) : applyHud(accent, flags));
     } catch (error) {
       console.error(error.message);
       process.exitCode = error.exitCode || 1;
@@ -295,9 +438,8 @@ async function main(argv, runtime = {}) {
   }
   if (command === "motion-runtime") {
     const action = positionals[1];
-    if (!['install', 'status'].includes(action)) {
-      console.error('usage: lithermes motion-runtime install|status [--audio] [--word-timing]');
-      process.exitCode = 2;
+    if (action === "install" && flags["dry-run"]) {
+      console.log(await motionRuntimePlan(flags));
       return;
     }
     const result = motionRuntime(action, flags);
@@ -358,7 +500,7 @@ async function main(argv, runtime = {}) {
     return;
   }
   if (command === "uninstall") {
-    const result = uninstallLitHermes(flags);
+    const result = flags["dry-run"] ? previewUninstall(flags) : uninstallLitHermes(flags);
     console.log(result.message);
     return;
   }
@@ -407,19 +549,7 @@ async function main(argv, runtime = {}) {
     if (result.ok !== false) scheduleUpdateSafely(command, flags, runtime);
     return;
   }
-  console.log([
-    "lithermes commands:",
-    "  install [--yes] [--dry-run] [--reconfigure-model] [--provider ID] [--model ID] [--effort LEVEL]",
-    "          [--child-provider ID] [--child-model ID] [--child-effort LEVEL]",
-    "          [--spinner] [--no-spinner] [--hud <accent>] [--no-hud] [--no-auto-update] [--hermes-home PATH]",
-    "  check [--offline] [--gateway-offline] [--hermes-home PATH]",
-    "  doctor [--offline] [--hermes-home PATH] [--hermes-repo PATH]",
-    "  motion-runtime install|status [--audio] [--word-timing]",
-    "  Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit ca251e3.",
-    "  uninstall [--yes] [--hermes-home PATH]",
-    "  hud [<accent>|off|--list] [--hermes-home PATH]   (Hermes HUD skin accents)",
-    "  version",
-  ].join("\n"));
+  console.log(helpText());
 }
 
-module.exports = { main, parseArgs };
+module.exports = { COMMAND_SPECS, helpText, main, parseArgs, validateArgs };

package/src/lib/check.js

@@ -1,7 +1,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
-const { configHasLitHermes, formatConcurrencyCapability, inspectHermesCapabilities, readConfig, readExternalSkillDirsConfig } = require("./config");
+const { configHasLitHermes, formatConcurrencyCapability, inspectHermesCapabilities, readConfig, readExternalSkillDirsConfig, readStatusBarFields, suggestStatusBarFields } = require("./config");
 const { detectHermesRuntimeRepo, detectHermesVersion, ensureHermesHome, expandHome, inspectHermesHostCapabilities, LitHermesError } = require("./hermesDiscovery");
 const { formatManagedRoute } = require("./modelRoutePolicy");
 const { inspectPythonCache } = require("./files");
@@ -223,6 +223,17 @@ function motionProbeLines(pluginPath, hermesHome) {
   ];
 }
 
+function formatStatusBarFields(configText) {
+  const suggested = suggestStatusBarFields(configText);
+  if (suggested) {
+    return `status bar fields: DEFAULT (suggest display.status_bar.fields: [${suggested.join(", ")}]; LitHermes does not write it)`;
+  }
+  const fields = readStatusBarFields(configText);
+  return fields === null
+    ? "status bar fields: UNKNOWN (config.yaml did not parse)"
+    : `status bar fields: CUSTOM (${fields.length} ${fields.length === 1 ? "field" : "fields"}, left as configured)`;
+}
+
 function doctorLitHermes(flags = {}) {
   const bundledBytecodeEntries = inspectPythonCache(assetRoot);
   const { hermesHome, hermesRepo } = ensureHermesHome(flags);
@@ -290,6 +301,7 @@ function doctorLitHermes(flags = {}) {
     `loaded plugin: ${loaded.status} (${loaded.reason})`,
     `skill shadow check: ${skillShadows.length ? "WARNING" : "PASS"}`,
     ...skillShadows.map(formatSkillShadowWarning),
+    formatStatusBarFields(configText),
     `auto-compaction: ${auto.status}${auto.reason ? ` (${auto.reason})` : ""}`,
 		`concurrency: ${formatConcurrencyCapability(concurrency)}`,
 		`recursion: ${recursion.status}${recursion.status === "hard" ? recursion.flatBy === "depth" ? ` (depth ${recursion.limit}, flat)` : ` (configured depth ${recursion.limit}, flat via orchestrator kill switch)` : ` (${recursion.reason})`}`,

package/src/lib/config.js

@@ -14,16 +14,8 @@ function readConfig(hermesHome) {
 }
 
 function findPluginsBlock(lines) {
-  const start = lines.findIndex((line) => /^plugins:\s*$/.test(line));
-  if (start === -1) return null;
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i += 1) {
-    if (/^\S/.test(lines[i]) && !/^---\s*$/.test(lines[i])) {
-      end = i;
-      break;
-    }
-  }
-  return { start, end, lines: lines.slice(start, end) };
+  const block = findTopBlock(lines, "plugins");
+  return block && { ...block, lines: lines.slice(block.start, block.end) };
 }
 
 function configHasLitHermes(text) {
@@ -31,7 +23,7 @@ function configHasLitHermes(text) {
   if (!block) return false;
   return block.lines.some((line, index) => {
     if (/^\s*enabled:\s*\[[^\]]*lithermes[^\]]*\]/.test(line)) return true;
-    if (!/^\s*enabled:\s*$/.test(line)) return false;
+    if (!/^\s*enabled:(\s+#.*)?\s*$/.test(line)) return false;
     for (let i = index + 1; i < block.lines.length; i += 1) {
       const child = block.lines[i];
       if (/^\s{2}\S/.test(child) && !/^\s{2,}-/.test(child)) return false;
@@ -46,11 +38,13 @@ function enableLitHermesConfig(text) {
   if (!text.trim()) {
     return "plugins:\n  enabled:\n    - lithermes\n";
   }
+  const eol = eolOf(text);
   const trailingNewline = text.endsWith("\n");
   const lines = text.split(/\r?\n/);
-  if (!trailingNewline && lines[lines.length - 1] === "") lines.pop();
+  if (trailingNewline) lines.pop();
   const block = findPluginsBlock(lines);
   if (block) {
+    openBlock(lines, block);
     for (let i = block.start + 1; i < block.end; i += 1) {
       const line = lines[i];
       if (/^\s{2}enabled:\s*\[[^\]]*\]/.test(line)) {
@@ -59,43 +53,53 @@ function enableLitHermesConfig(text) {
           values.push("lithermes");
           return `[${values.join(", ")}]`;
         });
-        return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+        return `${lines.join(eol)}${trailingNewline ? eol : ""}`;
       }
-      if (/^\s{2}enabled:\s*$/.test(line)) {
-        lines.splice(i + 1, 0, "    - lithermes");
-        return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+      if (/^\s{2}enabled:(\s+#.*)?\s*$/.test(line)) {
+        // Match the list's own indentation; Hermes writes indentless sequences.
+        const next = lines.slice(i + 1, block.end).find((item) => item.trim() && !/^\s*#/.test(item));
+        const indent = /^(\s*)-(\s|$)/.exec(next || "")?.[1] ?? "    ";
+        lines.splice(i + 1, 0, `${indent}- lithermes`);
+        return `${lines.join(eol)}${trailingNewline ? eol : ""}`;
       }
     }
     lines.splice(block.start + 1, 0, "  enabled:", "    - lithermes");
-    return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+    return `${lines.join(eol)}${trailingNewline ? eol : ""}`;
   }
-  const suffix = text.endsWith("\n") ? "" : "\n";
-  return `${text}${suffix}plugins:\n  enabled:\n    - lithermes\n`;
+  const suffix = trailingNewline ? "" : eol;
+  return `${text}${suffix}${["plugins:", "  enabled:", "    - lithermes", ""].join(eol)}`;
 }
 
 function disableLitHermesConfig(text) {
+  const eol = eolOf(text);
   const trailingNewline = text.endsWith("\n");
   const lines = text.split(/\r?\n/);
+  if (trailingNewline) lines.pop();
   const block = findPluginsBlock(lines);
   if (!block) return text;
+  let inEnabled = false;
   for (let i = block.start + 1; i < block.end; i += 1) {
     const line = lines[i];
+    // Only plugins.enabled items are removed; a `disabled:` entry belongs to the user.
+    if (/^\s+[^\s#-]/.test(line)) inEnabled = /^\s+enabled:(\s+#.*)?\s*$/.test(line);
     if (/^\s{2}enabled:\s*\[[^\]]*lithermes[^\]]*\]/.test(line)) {
       const inner = line.match(/\[([^\]]*)\]/)?.[1] || "";
       const values = inner.split(",").map((item) => item.trim()).filter((item) => item && item !== "lithermes");
       lines[i] = `  enabled: [${values.join(", ")}]`;
     }
-    if (/^\s*-\s*lithermes\s*$/.test(line)) {
+    if (inEnabled && /^\s*-\s*lithermes\s*$/.test(line)) {
       lines.splice(i, 1);
       i -= 1;
       block.end -= 1;
     }
   }
-  return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+  return `${lines.join(eol)}${trailingNewline ? eol : ""}`;
 }
 
+// A top-level `key:` opens a block even with a trailing comment or an empty
+// flow map `{}`; openBlock() drops the `{}` only when a child is being added.
 function findTopBlock(lines, key) {
-  const re = new RegExp(`^${key}:\\s*$`);
+  const re = new RegExp(`^${key}:(\\s*\\{\\s*\\})?(\\s+#.*)?\\s*$`);
   const start = lines.findIndex((line) => re.test(line));
   if (start === -1) return null;
   let end = lines.length;
@@ -108,6 +112,18 @@ function findTopBlock(lines, key) {
   return { start, end };
 }
 
+const eolOf = (text) => (String(text || "").includes("\r\n") ? "\r\n" : "\n");
+
+// Rejoin in the file's own line ending; trailing blank lines collapse to one ending.
+function joinLines(lines, eol, extra = []) {
+  while (lines.length && lines[lines.length - 1] === "") lines.pop();
+  return [...lines, ...extra, ""].join(eol);
+}
+
+function openBlock(lines, block) {
+  lines[block.start] = lines[block.start].replace(/\s*\{\s*\}/, "");
+}
+
 function readDisplaySkinConfig(text) {
   const lines = String(text || "").split(/\r?\n/);
   const block = findTopBlock(lines, "display");
@@ -122,23 +138,21 @@ function readDisplaySkinConfig(text) {
 function setDisplaySkinConfig(text, skinName) {
   const value = String(skinName || "").trim();
   if (!value) return text;
-  const trailingNewline = !text || text.endsWith("\n");
+  const eol = eolOf(text);
   const lines = String(text || "").split(/\r?\n/);
-  if (!trailingNewline && lines[lines.length - 1] === "") lines.pop();
   const block = findTopBlock(lines, "display");
   if (block) {
     for (let i = block.start + 1; i < block.end; i += 1) {
       if (/^\s{2}skin:\s*/.test(lines[i])) {
         lines[i] = `  skin: ${value}`;
-        return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+        return joinLines(lines, eol);
       }
     }
+    openBlock(lines, block);
     lines.splice(block.start + 1, 0, `  skin: ${value}`);
-    return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+    return joinLines(lines, eol);
   }
-  const body = lines.join("\n").replace(/\n*$/, "");
-  const prefix = body ? `${body}\n` : "";
-  return `${prefix}display:\n  skin: ${value}\n`;
+  return joinLines(lines, eol, ["display:", `  skin: ${value}`]);
 }
 
 function readTuiAgentsNudgeConfig(text) {
@@ -156,17 +170,15 @@ function readTuiAgentsNudgeConfig(text) {
 // Set only when absent: an explicit user value, true or false, is preserved.
 function setTuiAgentsNudgeConfig(text) {
   if (readTuiAgentsNudgeConfig(text) !== null) return text;
-  const trailingNewline = !text || text.endsWith("\n");
+  const eol = eolOf(text);
   const lines = String(text || "").split(/\r?\n/);
-  if (!trailingNewline && lines[lines.length - 1] === "") lines.pop();
   const block = findTopBlock(lines, "display");
   if (block) {
+    openBlock(lines, block);
     lines.splice(block.start + 1, 0, "  tui_agents_nudge: true");
-    return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+    return joinLines(lines, eol);
   }
-  const body = lines.join("\n").replace(/\n*$/, "");
-  const prefix = body ? `${body}\n` : "";
-  return `${prefix}display:\n  tui_agents_nudge: true\n`;
+  return joinLines(lines, eol, ["display:", "  tui_agents_nudge: true"]);
 }
 
 function clearDisplaySkinConfig(text) {
@@ -179,7 +191,7 @@ function clearDisplaySkinConfig(text) {
       break;
     }
   }
-  return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+  return joinLines(lines, eolOf(text));
 }
 
 function readOutputStyleConfig(text) {
@@ -227,13 +239,56 @@ function readExternalSkillDirsConfig(text) {
   }
 }
 
+// Hermes `display.status_bar.fields` only chooses which built-in segments show
+// (the order is fixed). Empty means the host default, which leaves out the
+// opt-in git branch. Doctor suggests this set and never writes it.
+const RECOMMENDED_STATUS_BAR_FIELDS = Object.freeze([
+  "model", "context_pct", "goal", "bg_subagents", "git_branch", "prompt_elapsed", "yolo",
+]);
+
+// The configured field list ([] when unset); null when config.yaml does not parse.
+function readStatusBarFields(text) {
+  const str = String(text || "");
+  if (!str.trim()) return [];
+  try {
+    const document = parseDocument(str, { strict: true, uniqueKeys: true });
+    if (document.errors.length) return null;
+    const fields = document.toJS()?.display?.status_bar?.fields;
+    return Array.isArray(fields) ? fields : [];
+  } catch {
+    return null;
+  }
+}
+
+// null = the user already chose fields, or the YAML is malformed (no guessing).
+function suggestStatusBarFields(text) {
+  const fields = readStatusBarFields(text);
+  return fields && fields.length === 0 ? RECOMMENDED_STATUS_BAR_FIELDS : null;
+}
+
+function yamlError(text) {
+  if (!String(text || "").trim()) return null;
+  const document = parseDocument(text, { strict: true, uniqueKeys: true });
+  return document.errors.length ? document.errors[0].message.split("\n")[0].replace(/:$/, "") : null;
+}
+
+// Fail closed when an edit would break a config that parses under the installer's
+// strict check; an already-malformed file keeps the append-only fallback.
+function assertConfigEdit(hermesHome, before, after, hint = "Edit config.yaml by hand.") {
+  const error = yamlError(after);
+  if (!error || yamlError(before)) return;
+  throw new Error(`${configPath(hermesHome)} left unchanged: the LitHermes edit would not parse as YAML (${error}). ${hint}`);
+}
+
 function writeConfig(hermesHome, text) {
+  assertConfigEdit(hermesHome, readConfig(hermesHome), text);
   fs.mkdirSync(hermesHome, { recursive: true });
   writeFileAtomic(configPath(hermesHome), text, "utf8");
 }
 
 module.exports = {
   ...modelConfig,
+  assertConfigEdit,
   clearDisplaySkinConfig,
   clearOutputStyleConfig,
   configHasLitHermes,
@@ -243,6 +298,9 @@ module.exports = {
   readConfig,
   readDisplaySkinConfig,
   readExternalSkillDirsConfig,
+  readStatusBarFields,
+  RECOMMENDED_STATUS_BAR_FIELDS,
+  suggestStatusBarFields,
   readOutputStyleConfig,
   readTuiAgentsNudgeConfig,
   setDisplaySkinConfig,

package/src/lib/hud.js

@@ -1,3 +1,4 @@
+const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline");
@@ -76,7 +77,7 @@ function listHud({ color = false, hermesHome = null } = {}) {
   return lines.join("\n");
 }
 
-function applyHud(token, flags = {}) {
+function accentOrThrow(token) {
   const entry = skins.findAccent(token);
   if (!entry) {
     const names = [
@@ -88,6 +89,11 @@ function applyHud(token, flags = {}) {
     err.exitCode = 4;
     throw err;
   }
+  return entry;
+}
+
+function applyHud(token, flags = {}) {
+  const entry = accentOrThrow(token);
   const home = resolveHome(flags);
   const written = skins.installSkins(home);
   const name = skins.skinName(entry.accent);
@@ -110,6 +116,31 @@ function clearHud(flags = {}) {
   return "LitHermes HUD cleared (display.skin removed). Restart Hermes to revert to the default skin.";
 }
 
+// Dry runs of `hud <accent>` and `hud off`: read the config and skins folder, write nothing.
+function previewHud(token, flags = {}) {
+  const entry = accentOrThrow(token);
+  const home = resolveHome(flags);
+  const name = skins.skinName(entry.accent);
+  const dir = skins.skinsDir(home);
+  const missing = [...skins.HUD_ACCENTS, skins.IGNITION, ...skins.NAMED_THEMES]
+    .filter((item) => !fs.existsSync(path.join(dir, `${skins.skinName(item.accent)}.yaml`)));
+  const before = readConfig(home);
+  return [
+    `DRY RUN: would set display.skin: ${name} (${entry.label})`,
+    `skins: would add ${missing.length} skin files -> ${dir}`,
+    `config: ${setDisplaySkinConfig(before, name) === before ? "already set; no change" : `would update ${path.join(home, "config.yaml")}`}`,
+    "Nothing was changed.",
+  ].join("\n");
+}
+
+function previewClearHud(flags = {}) {
+  const home = resolveHome(flags);
+  const before = readConfig(home);
+  return clearDisplaySkinConfig(before) === before
+    ? "DRY RUN: display.skin is not set, so `hud off` would change nothing.\nNothing was changed."
+    : `DRY RUN: would remove display.skin from ${path.join(home, "config.yaml")}\nNothing was changed.`;
+}
+
 // Interactive accent picker used during `lithermes install` on a TTY.
 // Returns the chosen accent entry, or null to skip (empty / unknown answer).
 function promptAccent({ input = process.stdin, output = process.stdout, color = false } = {}) {
@@ -132,4 +163,4 @@ function promptAccent({ input = process.stdin, output = process.stdout, color =
   });
 }
 
-module.exports = { resolveHome, listHud, applyHud, clearHud, promptAccent };
+module.exports = { resolveHome, listHud, applyHud, clearHud, previewClearHud, previewHud, promptAccent };