lithermes-ai 0.5.0

package/src/lib/config.js

@@ -0,0 +1,170 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { writeFileAtomic } = require("./files");
+
+function configPath(hermesHome) {
+  return path.join(hermesHome, "config.yaml");
+}
+
+function readConfig(hermesHome) {
+  const file = configPath(hermesHome);
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+}
+
+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) };
+}
+
+function configHasLitHermes(text) {
+  const block = findPluginsBlock(text.split(/\r?\n/));
+  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;
+    for (let i = index + 1; i < block.lines.length; i += 1) {
+      const child = block.lines[i];
+      if (/^\s{2}\S/.test(child) && !/^\s{4}-/.test(child)) return false;
+      if (/^\s*-\s*lithermes\s*$/.test(child)) return true;
+    }
+    return false;
+  });
+}
+
+function enableLitHermesConfig(text) {
+  if (configHasLitHermes(text)) return text;
+  if (!text.trim()) {
+    return "plugins:\n  enabled:\n    - lithermes\n";
+  }
+  const trailingNewline = text.endsWith("\n");
+  const lines = text.split(/\r?\n/);
+  if (!trailingNewline && lines[lines.length - 1] === "") lines.pop();
+  const block = findPluginsBlock(lines);
+  if (block) {
+    for (let i = block.start + 1; i < block.end; i += 1) {
+      const line = lines[i];
+      if (/^\s{2}enabled:\s*\[[^\]]*\]/.test(line)) {
+        lines[i] = line.replace(/\[([^\]]*)\]/, (_match, inner) => {
+          const values = inner.split(",").map((item) => item.trim()).filter(Boolean);
+          values.push("lithermes");
+          return `[${values.join(", ")}]`;
+        });
+        return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+      }
+      if (/^\s{2}enabled:\s*$/.test(line)) {
+        lines.splice(i + 1, 0, "    - lithermes");
+        return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+      }
+    }
+    lines.splice(block.start + 1, 0, "  enabled:", "    - lithermes");
+    return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+  }
+  const suffix = text.endsWith("\n") ? "" : "\n";
+  return `${text}${suffix}plugins:\n  enabled:\n    - lithermes\n`;
+}
+
+function disableLitHermesConfig(text) {
+  const trailingNewline = text.endsWith("\n");
+  const lines = text.split(/\r?\n/);
+  const block = findPluginsBlock(lines);
+  if (!block) return text;
+  for (let i = block.start + 1; i < block.end; i += 1) {
+    const line = lines[i];
+    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)) {
+      lines.splice(i, 1);
+      i -= 1;
+      block.end -= 1;
+    }
+  }
+  return `${lines.join("\n")}${trailingNewline ? "\n" : ""}`;
+}
+
+function findTopBlock(lines, key) {
+  const re = new RegExp(`^${key}:\\s*$`);
+  const start = lines.findIndex((line) => re.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 };
+}
+
+function readDisplaySkinConfig(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const block = findTopBlock(lines, "display");
+  if (!block) return null;
+  for (let i = block.start + 1; i < block.end; i += 1) {
+    const m = /^\s{2}skin:\s*(\S.*?)\s*$/.exec(lines[i]);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+function setDisplaySkinConfig(text, skinName) {
+  const value = String(skinName || "").trim();
+  if (!value) return text;
+  const trailingNewline = !text || text.endsWith("\n");
+  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`;
+      }
+    }
+    lines.splice(block.start + 1, 0, `  skin: ${value}`);
+    return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+  }
+  const body = lines.join("\n").replace(/\n*$/, "");
+  const prefix = body ? `${body}\n` : "";
+  return `${prefix}display:\n  skin: ${value}\n`;
+}
+
+function clearDisplaySkinConfig(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const block = findTopBlock(lines, "display");
+  if (!block) return text;
+  for (let i = block.start + 1; i < block.end; i += 1) {
+    if (/^\s{2}skin:\s*/.test(lines[i])) {
+      lines.splice(i, 1);
+      break;
+    }
+  }
+  return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+}
+
+function writeConfig(hermesHome, text) {
+  fs.mkdirSync(hermesHome, { recursive: true });
+  writeFileAtomic(configPath(hermesHome), text, "utf8");
+}
+
+module.exports = {
+  clearDisplaySkinConfig,
+  configHasLitHermes,
+  configPath,
+  disableLitHermesConfig,
+  enableLitHermesConfig,
+  readConfig,
+  readDisplaySkinConfig,
+  setDisplaySkinConfig,
+  writeConfig,
+};

package/src/lib/files.js

@@ -0,0 +1,65 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function listFiles(root) {
+  const out = [];
+  if (!fs.existsSync(root)) return out;
+  for (const name of fs.readdirSync(root)) {
+    if (name === "__pycache__" || name.endsWith(".pyc")) continue;
+    const full = path.join(root, name);
+    const stat = fs.statSync(full);
+    if (stat.isDirectory()) {
+      out.push(...listFiles(full));
+    } else if (stat.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function sha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function copyTree(src, dest) {
+  const copied = [];
+  for (const file of listFiles(src)) {
+    const relative = path.relative(src, file);
+    const target = path.join(dest, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(file, target);
+    copied.push({ path: relative, sha256: sha256(target) });
+  }
+  return copied;
+}
+
+// Atomic write: write to a .tmp sibling, fsync, then rename into place.
+// fsync failure is non-fatal (degrades gracefully — still renames).
+function writeFileAtomic(filePath, data, encoding) {
+  const tmp = `${filePath}.tmp`;
+  const enc = encoding || "utf8";
+  const fd = fs.openSync(tmp, "w");
+  try {
+    fs.writeSync(fd, data, null, enc);
+    try {
+      fs.fsyncSync(fd);
+    } catch {
+      // fsync not supported on all platforms/fs; degrade gracefully
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, filePath);
+}
+
+function removeEmptyDirs(dir, stopAt) {
+  let current = dir;
+  while (current && current !== stopAt && current.startsWith(stopAt) && fs.existsSync(current)) {
+    if (fs.readdirSync(current).length > 0) break;
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
+module.exports = { copyTree, listFiles, removeEmptyDirs, sha256, writeFileAtomic };

package/src/lib/hermesDiscovery.js

@@ -0,0 +1,50 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+class LitHermesError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+function expandHome(value) {
+  if (!value) return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+function defaultHermesHome(flags = {}) {
+  return path.resolve(expandHome(flags["hermes-home"] || process.env.HERMES_HOME || "~/.hermes"));
+}
+
+function defaultHermesRepo(flags = {}, hermesHome = defaultHermesHome(flags)) {
+  if (flags["hermes-repo"]) return path.resolve(expandHome(flags["hermes-repo"]));
+  const candidate = path.join(hermesHome, "hermes-agent");
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+function ensureHermesHome(flags = {}, { forInstall = false } = {}) {
+  const hermesHome = defaultHermesHome(flags);
+  if (!fs.existsSync(hermesHome)) {
+    if (forInstall) {
+      fs.mkdirSync(hermesHome, { recursive: true });
+    } else {
+      throw new LitHermesError(`Hermes installation not found at ${hermesHome}. Pass --hermes-home PATH to select it.`, 2);
+    }
+  }
+  return {
+    hermesHome,
+    hermesRepo: defaultHermesRepo(flags, hermesHome),
+  };
+}
+
+module.exports = {
+  LitHermesError,
+  defaultHermesHome,
+  defaultHermesRepo,
+  ensureHermesHome,
+  expandHome,
+};

package/src/lib/hud.js

@@ -0,0 +1,121 @@
+const os = require("node:os");
+const path = require("node:path");
+const readline = require("node:readline");
+const skins = require("./skins");
+const {
+  readConfig,
+  writeConfig,
+  setDisplaySkinConfig,
+  clearDisplaySkinConfig,
+  readDisplaySkinConfig,
+} = require("./config");
+
+function resolveHome(flags = {}) {
+  const fromFlag = flags["hermes-home"];
+  if (typeof fromFlag === "string" && fromFlag.trim()) return path.resolve(fromFlag);
+  const env = (process.env.HERMES_HOME || "").trim();
+  if (env) return path.resolve(env);
+  return path.join(os.homedir(), ".hermes");
+}
+
+// ANSI helpers — all output goes through these so no-color paths stay clean.
+const BOLD  = (s, on) => on ? `\x1b[1m${s}\x1b[22m` : s;
+const DIM   = (s, on) => on ? `\x1b[2m${s}\x1b[22m` : s;
+const FG256 = (code, s, on) => on ? `\x1b[38;5;${code}m${s}\x1b[39m` : s;
+
+function listHud({ color = false, hermesHome = null } = {}) {
+  const current = hermesHome ? readDisplaySkinConfig(readConfig(hermesHome)) : null;
+
+  // Header — fire brand mark + neon label when color is on
+  const brand = color ? "🔥" : "[fire]";
+  const header = color
+    ? `${brand} ${BOLD("LitHermes HUD", true)} ${DIM("— neon accents", true)}`
+    : `${brand} LitHermes HUD — neon accents`;
+  const lines = [header, ""];
+
+  skins.HUD_ACCENTS.forEach((a, i) => {
+    const sw = skins.swatch(a.hex, { color, code: a.code });
+    const isActive = current === skins.skinName(a.accent);
+
+    // Active indicator: 🔥 in color, * in plain
+    const activeMark = isActive ? (color ? " 🔥" : " *") : "";
+
+    // Mood label — dimmed in color mode for a secondary-info feel
+    const moodText = a.mood ? `  ${DIM(a.mood, color)}` : "";
+
+    // Accent name — bold + accent color when active, plain bold otherwise
+    const accentLabel = color
+      ? (isActive
+          ? BOLD(FG256(a.code, a.accent.padEnd(9), true), true)
+          : BOLD(a.accent.padEnd(9), true))
+      : a.accent.padEnd(9);
+
+    const hexLabel = color ? DIM(a.hex, true) : a.hex;
+
+    lines.push(
+      `  ${String(i + 1).padStart(2)}. ${sw} ${accentLabel} ${hexLabel}${moodText}${activeMark}`
+    );
+  });
+
+  lines.push("");
+  const applyCmd  = color ? BOLD("lithermes hud <accent>", true) : "lithermes hud <accent>";
+  const clearCmd  = color ? BOLD("lithermes hud off", true) : "lithermes hud off";
+  const skinCmd   = color ? BOLD("/skin lithermes-<accent>", true) : "/skin lithermes-<accent>";
+  lines.push(`Apply:     ${applyCmd}   (e.g. lithermes hud rose, or hud 1)`);
+  lines.push(`Clear:     ${clearCmd}`);
+  lines.push(`In Hermes: ${skinCmd}  (or set display.skin in config.yaml)`);
+  return lines.join("\n");
+}
+
+function applyHud(token, flags = {}) {
+  const entry = skins.findAccent(token);
+  if (!entry) {
+    const names = skins.HUD_ACCENTS.map((a) => a.accent).join(", ");
+    const err = new Error(`unknown accent '${token}'. choose one of: ${names}`);
+    err.exitCode = 4;
+    throw err;
+  }
+  const home = resolveHome(flags);
+  const written = skins.installSkins(home);
+  const name = skins.skinName(entry.accent);
+  const before = readConfig(home);
+  const after = setDisplaySkinConfig(before, name);
+  if (after !== before) writeConfig(home, after);
+  return [
+    `LitHermes HUD set to ${entry.label} (${name}).`,
+    `Installed ${written.length} skins -> ${skins.skinsDir(home)}`,
+    `config: display.skin: ${name}`,
+    `Restart Hermes, or run \`/skin ${name}\` in a session, to apply.`,
+  ].join("\n");
+}
+
+function clearHud(flags = {}) {
+  const home = resolveHome(flags);
+  const before = readConfig(home);
+  const after = clearDisplaySkinConfig(before);
+  if (after !== before) writeConfig(home, after);
+  return "LitHermes HUD cleared (display.skin removed). Restart Hermes to revert to the default skin.";
+}
+
+// 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 } = {}) {
+  return new Promise((resolve) => {
+    output.write("Choose a Hermes HUD accent:\n");
+    skins.HUD_ACCENTS.forEach((a, i) => {
+      const sw = skins.swatch(a.hex, { color, code: a.code });
+      output.write(`  ${String(i + 1).padStart(2)}. ${sw} ${a.accent}\n`);
+    });
+    const rl = readline.createInterface({ input, output });
+    // Resolve to null if the stream closes without an answer (e.g. piped input
+    // that ends without a newline); the question callback resolves first when an
+    // answer arrives, so this is a no-op in the normal path.
+    rl.on("close", () => resolve(null));
+    rl.question("Pick 1-10 or name (Enter to skip): ", (answer) => {
+      resolve(skins.findAccent(answer)); // resolve BEFORE close so the answer wins
+      rl.close();
+    });
+  });
+}
+
+module.exports = { resolveHome, listHud, applyHud, clearHud, promptAccent };

package/src/lib/install.js

@@ -0,0 +1,159 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { disableLitHermesConfig, enableLitHermesConfig, readConfig, writeConfig } = require("./config");
+const { copyTree, listFiles, removeEmptyDirs, sha256, writeFileAtomic } = require("./files");
+const { ensureHermesHome, LitHermesError } = require("./hermesDiscovery");
+const { patchInstalledHermes, rollbackPatches } = require("./patch");
+const { installSkins } = require("./skins");
+
+const packageRoot = path.resolve(__dirname, "..", "..");
+const assetRoot = path.join(packageRoot, "assets", "lithermes-plugin");
+
+function manifestPath(hermesHome) {
+  return path.join(hermesHome, "lithermes", "install-manifest.json");
+}
+
+function pluginDest(hermesHome) {
+  return path.join(hermesHome, "plugins", "lithermes");
+}
+
+function withLock(hermesHome, fn) {
+  const lock = path.join(hermesHome, "lithermes", "install.lock");
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+  let fd;
+  try {
+    fd = fs.openSync(lock, "wx");
+    fs.writeFileSync(fd, String(process.pid));
+  } catch {
+    throw new LitHermesError(`LitHermes install lock already exists at ${lock}`, 3);
+  }
+  try {
+    return fn();
+  } finally {
+    if (fd) fs.closeSync(fd);
+    if (fs.existsSync(lock)) fs.unlinkSync(lock);
+  }
+}
+
+function loadManifest(hermesHome) {
+  const file = manifestPath(hermesHome);
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function installedMatchesManifest(hermesHome, manifest) {
+  if (!manifest) return false;
+  const dest = pluginDest(hermesHome);
+  return manifest.files.every((entry) => {
+    const file = path.join(dest, entry.path);
+    return fs.existsSync(file) && sha256(file) === entry.sha256;
+  });
+}
+
+function installLitHermes(flags = {}) {
+  const { hermesHome, hermesRepo } = ensureHermesHome(flags, { forInstall: true });
+  const dest = pluginDest(hermesHome);
+  const dryRun = Boolean(flags["dry-run"]);
+  const onProgress = typeof flags.onProgress === "function" ? flags.onProgress : () => {};
+  if (dryRun) {
+    return {
+      message: [
+        "DRY RUN: would install LitHermes",
+        `plugin: ${dest}`,
+        `config: ${path.join(hermesHome, "config.yaml")}`,
+        `manifest: ${manifestPath(hermesHome)}`,
+      ].join("\n"),
+    };
+  }
+  if (!flags.yes) {
+    throw new LitHermesError("Refusing to mutate Hermes config without --yes. Re-run with --dry-run to inspect changes.", 4);
+  }
+  onProgress("Preparing Hermes config");
+  return withLock(hermesHome, () => {
+    onProgress("Inspecting existing plugin");
+    const existingManifest = loadManifest(hermesHome);
+    const wasUpToDate = fs.existsSync(dest) && installedMatchesManifest(hermesHome, existingManifest);
+    if (fs.existsSync(dest) && !installedMatchesManifest(hermesHome, existingManifest) && !flags.force) {
+      throw new LitHermesError(`Existing LitHermes plugin at ${dest} is not manifest-owned. Use --force after backing it up.`, 5);
+    }
+    onProgress("Copying LitHermes payload");
+    fs.rmSync(dest, { recursive: true, force: true });
+    const files = copyTree(assetRoot, dest);
+    onProgress("Writing Hermes config");
+    const beforeConfig = readConfig(hermesHome);
+    const afterConfig = enableLitHermesConfig(beforeConfig);
+    writeConfig(hermesHome, afterConfig);
+    onProgress("Installing HUD skins");
+    let skinFiles = [];
+    try {
+      skinFiles = installSkins(hermesHome);
+    } catch {
+      // HUD skins are optional polish; never fail the install over them.
+    }
+    onProgress("Recording install manifest");
+    const manifest = {
+      version: require(path.join(packageRoot, "package.json")).version,
+      installedAt: new Date().toISOString(),
+      pluginPath: dest,
+      configPath: path.join(hermesHome, "config.yaml"),
+      files,
+      configAddedLitHermes: beforeConfig !== afterConfig,
+    };
+    fs.mkdirSync(path.dirname(manifestPath(hermesHome)), { recursive: true });
+    writeFileAtomic(manifestPath(hermesHome), JSON.stringify(manifest, null, 2), "utf8");
+    let patchResult = null;
+    let patchWarning = null;
+    const shouldPatch = Boolean(flags["patch-installed-hermes"] || (!flags["no-patch-installed-hermes"] && hermesRepo));
+    if (shouldPatch) {
+      onProgress("Checking Hermes compatibility patches");
+      try {
+        patchResult = patchInstalledHermes({ hermesHome, hermesRepo, force: flags.force });
+      } catch (error) {
+        if (flags["patch-installed-hermes"]) throw error;
+        patchWarning = error.message;
+      }
+    }
+    const lines = [
+      wasUpToDate ? "LitHermes already up to date" : "Installed LitHermes",
+      `plugin: ${dest}`,
+    ];
+    if (patchResult) lines.push(`patches: ${patchResult.changed.length ? patchResult.changed.join(", ") : "none needed"}`);
+    if (patchWarning) lines.push(`patches: skipped (${patchWarning})`);
+    if (skinFiles.length) lines.push(`HUD skins: ${skinFiles.length} accents installed — pick one with \`npx lithermes hud <accent>\``);
+    lines.push("Restart any running Hermes gateway to load new plugins.");
+    return { message: lines.join("\n") };
+  });
+}
+
+function uninstallLitHermes(flags = {}) {
+  const { hermesHome } = ensureHermesHome(flags);
+  if (!flags.yes) {
+    throw new LitHermesError("Refusing to uninstall without --yes.", 4);
+  }
+  return withLock(hermesHome, () => {
+    const rollback = flags["rollback-patches"] ? rollbackPatches({ hermesHome }) : null;
+    const manifest = loadManifest(hermesHome);
+    if (!manifest) return { message: rollback ? `LitHermes is not installed by this installer.\n${rollback.message}` : "LitHermes is not installed by this installer." };
+    const dest = pluginDest(hermesHome);
+    for (const entry of [...manifest.files].reverse()) {
+      const file = path.join(dest, entry.path);
+      if (fs.existsSync(file) && sha256(file) === entry.sha256) {
+        fs.unlinkSync(file);
+        removeEmptyDirs(path.dirname(file), dest);
+      }
+    }
+    if (fs.existsSync(dest) && listFiles(dest).length === 0) fs.rmSync(dest, { recursive: true, force: true });
+    writeConfig(hermesHome, disableLitHermesConfig(readConfig(hermesHome)));
+    fs.unlinkSync(manifestPath(hermesHome));
+    return { message: rollback ? `Uninstalled LitHermes\n${rollback.message}` : "Uninstalled LitHermes" };
+  });
+}
+
+module.exports = {
+  assetRoot,
+  installLitHermes,
+  loadManifest,
+  manifestPath,
+  pluginDest,
+  uninstallLitHermes,
+};