@litfamily/lithermes 1.0.0

package/src/lib/patch.js

@@ -0,0 +1,153 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { sha256, writeFileAtomic } = require("./files");
+const { LitHermesError } = require("./hermesDiscovery");
+
+function patchManifestPath(hermesHome) {
+  return path.join(hermesHome, "lithermes", "patch-manifest.json");
+}
+
+function patchTarget(repo, relative, marker, additions) {
+  const file = path.join(repo, relative);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  const source = fs.readFileSync(file, "utf8");
+  if (additions.every((text) => source.includes(text))) {
+    return null;
+  }
+  if (!source.includes(marker)) {
+    throw new LitHermesError(`Unsupported Hermes preimage for ${relative}; refusing to patch without a known marker.`, 8);
+  }
+  const backup = `${file}.lithermes.bak`;
+  fs.copyFileSync(file, backup);
+  const beforeHash = sha256(file);
+  const backupHash = sha256(backup);
+  const patched = `${source.replace(/\s*$/, "\n")}\n# LitHermes compatibility patch\n${additions.map((text) => `# ${text}`).join("\n")}\n`;
+  writeFileAtomic(file, patched, "utf8");
+  return {
+    file,
+    relative,
+    backup,
+    beforeHash,
+    backupHash,
+    patchedHash: sha256(file),
+  };
+}
+
+function patchCliPayloadDispatch(repo) {
+  const relative = "cli.py";
+  const file = path.join(repo, relative);
+  if (!fs.existsSync(file)) return null;
+  const source = fs.readFileSync(file, "utf8");
+  if (source.includes("_pending_input.put") && source.includes("agent_message") && source.includes("ast.literal_eval")) {
+    return null;
+  }
+
+  const marker = [
+    "                        result = resolve_plugin_command_result(",
+    "                            plugin_handler(user_args)",
+    "                        )",
+    "                        if result:",
+    "                            _cprint(str(result))",
+  ].join("\n");
+  if (!source.includes(marker)) {
+    throw new LitHermesError(`Unsupported Hermes preimage for ${relative}; plugin command dispatch block not recognized.`, 8);
+  }
+
+  const replacement = [
+    "                        result = resolve_plugin_command_result(",
+    "                            plugin_handler(user_args)",
+    "                        )",
+    "                        if isinstance(result, str) and \"agent_message\" in result:",
+    "                            try:",
+    "                                parsed = ast.literal_eval(result)",
+    "                            except (SyntaxError, ValueError):",
+    "                                parsed = None",
+    "                            if isinstance(parsed, dict):",
+    "                                result = parsed",
+    "                        if isinstance(result, dict) and result.get(\"agent_message\"):",
+    "                            display = result.get(\"display\") or result.get(\"message\")",
+    "                            if display:",
+    "                                _cprint(str(display))",
+    "                            if hasattr(self, '_pending_input'):",
+    "                                self._pending_input.put(str(result[\"agent_message\"]))",
+    "                        elif result:",
+    "                            _cprint(str(result))",
+  ].join("\n");
+
+  const backup = `${file}.lithermes.bak`;
+  fs.copyFileSync(file, backup);
+  const beforeHash = sha256(file);
+  const backupHash = sha256(backup);
+  writeFileAtomic(file, source.replace(marker, replacement), "utf8");
+  return {
+    file,
+    relative,
+    backup,
+    beforeHash,
+    backupHash,
+    patchedHash: sha256(file),
+  };
+}
+
+function patchInstalledHermes({ hermesHome, hermesRepo }) {
+  if (!hermesRepo || !fs.existsSync(hermesRepo)) {
+    throw new LitHermesError("Cannot patch Hermes because --hermes-repo was not found. Pass --hermes-repo PATH or run doctor first.", 8);
+  }
+  const changed = [];
+  const records = [];
+  const cli = patchCliPayloadDispatch(hermesRepo);
+  if (cli) {
+    changed.push("cli.py");
+    records.push(cli);
+  }
+  const gateway = patchTarget(hermesRepo, path.join("gateway", "run.py"), "lithermes-patch-target:gateway", [
+    'command.replace("_", "-")',
+    "_plugin_agent_dispatch_payload",
+  ]);
+  if (gateway) {
+    changed.push("gateway/run.py");
+    records.push(gateway);
+  }
+  const plugins = patchTarget(hermesRepo, path.join("hermes_cli", "plugins.py"), "lithermes-patch-target:plugins", [
+    "auto_load",
+    "plugins.enabled",
+  ]);
+  if (plugins) {
+    changed.push("hermes_cli/plugins.py");
+    records.push(plugins);
+  }
+  fs.mkdirSync(path.dirname(patchManifestPath(hermesHome)), { recursive: true });
+  writeFileAtomic(patchManifestPath(hermesHome), JSON.stringify({ patchedAt: new Date().toISOString(), records }, null, 2), "utf8");
+  return { changed, records };
+}
+
+function rollbackPatches({ hermesHome }) {
+  const manifest = patchManifestPath(hermesHome);
+  if (!fs.existsSync(manifest)) {
+    return { message: "No LitHermes patches to roll back." };
+  }
+  const parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
+  const restored = [];
+  for (const record of [...parsed.records].reverse()) {
+    if (!fs.existsSync(record.file) || !fs.existsSync(record.backup)) {
+      throw new LitHermesError(`Cannot roll back ${record.relative}; patched file or backup is missing.`, 9);
+    }
+    if (sha256(record.file) !== record.patchedHash || sha256(record.backup) !== record.backupHash) {
+      throw new LitHermesError(`Cannot roll back ${record.relative}; file hash changed after patch.`, 9);
+    }
+    fs.copyFileSync(record.backup, record.file);
+    fs.unlinkSync(record.backup);
+    restored.push(record.relative);
+  }
+  fs.unlinkSync(manifest);
+  return { message: `Rolled back LitHermes patches: ${restored.join(", ") || "none"}` };
+}
+
+module.exports = {
+  patchCliPayloadDispatch,
+  patchInstalledHermes,
+  patchManifestPath,
+  rollbackPatches,
+};

package/src/lib/skillLoop.js

@@ -0,0 +1,62 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { resolveHome } = require("./hud");
+
+function hermesInterpreter(env = process.env) {
+  if (env.LITHERMES_PYTHON) return env.LITHERMES_PYTHON;
+  for (const entry of (env.PATH || "").split(path.delimiter)) {
+    const executable = path.join(entry, "hermes");
+    try {
+      const first = fs.readFileSync(executable, "utf8").split(/\r?\n/, 1)[0];
+      const candidate = first.startsWith("#!/") ? first.slice(2).trim() : "";
+      if (!candidate.includes(" ") && /python(?:\d+(?:\.\d+)*)?$/.test(path.basename(candidate))) {
+        return candidate;
+      }
+    } catch {
+      // Keep looking; the final python3 fallback is explicit and deterministic.
+    }
+  }
+  return "python3";
+}
+
+function installedModule(hermesHome) {
+  const pluginRoot = path.join(hermesHome, "plugins", "lithermes");
+  const modulePath = path.join(pluginRoot, "skill_loop.py");
+  let pluginStat;
+  let moduleStat;
+  try {
+    pluginStat = fs.lstatSync(pluginRoot);
+    moduleStat = fs.lstatSync(modulePath);
+  } catch {
+    const error = new Error(`LitHermes skill-loop is not installed under ${pluginRoot}; run the normal installer first.`);
+    error.exitCode = 2;
+    throw error;
+  }
+  if (!pluginStat.isDirectory() || pluginStat.isSymbolicLink() || !moduleStat.isFile() || moduleStat.isSymbolicLink()) {
+    const error = new Error("Installed LitHermes skill-loop path is unsafe.");
+    error.exitCode = 2;
+    throw error;
+  }
+  return modulePath;
+}
+
+function runSkillLoop(args, flags = {}, runtime = {}) {
+  const hermesHome = resolveHome(flags);
+  const env = { ...(runtime.env || process.env), HERMES_HOME: hermesHome, PYTHONDONTWRITEBYTECODE: "1" };
+  const result = (runtime.spawnSync || spawnSync)(
+    hermesInterpreter(env),
+    [installedModule(hermesHome), ...args],
+    { cwd: runtime.cwd || process.cwd(), encoding: "utf8", env, timeout: 30000 },
+  );
+  if (result.error) {
+    const error = new Error("LitHermes skill-loop Python bridge failed to start.");
+    error.exitCode = 2;
+    throw error;
+  }
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  return Number.isInteger(result.status) ? result.status : 2;
+}
+
+module.exports = { hermesInterpreter, installedModule, runSkillLoop };

package/src/lib/skillPayload.js

@@ -0,0 +1,306 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { sha256 } = require("./files");
+const {
+  captureRegularFile,
+  parseJsonRejectingDuplicateKeys,
+  revalidateDescriptorCapture,
+  verifyCanonicalCorpus,
+} = require("./canonicalCorpus");
+
+const MAX_PAYLOAD_MANIFEST_BYTES = 1024 * 1024;
+const MAX_PAYLOAD_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_PAYLOAD_TOTAL_BYTES = 16 * 1024 * 1024;
+
+const requiredSkills = [
+  "lit-burnoff-file", "autoconference", "autoresearch", "browser-drive", "comment-checker", "debugging",
+  "deep-interview",
+  "frontend-ui-ux", "lit-commit", "lit-crucible", "lit-init",
+  "lit-korean", "lit-comprehend", "lit-handoff", "lit-plan", "lit-recap",
+  "lit-scientific-visualization", "litgoal", "litresearch", "litwork", "lsp",
+  "lsp-setup", "lit-code", "refactor", "lit-burnoff", "review-work",
+  "rules", "skill-observer", "start-work", "structural-search", "visual-qa", "wikify",
+];
+
+function inspectManifest(manifest, verifySourceHash) {
+  const exactKeys = (value, expected) => value !== null
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...expected].sort());
+  if (!exactKeys(manifest, ["syncedAt", "source", "sourceHash", "files"]) || !Array.isArray(manifest.files)) {
+    return { entries: new Map(), issue: "manifest schema fields invalid" };
+  }
+  if (
+    typeof manifest.syncedAt !== "string"
+    || Number.isNaN(Date.parse(manifest.syncedAt))
+    || new Date(manifest.syncedAt).toISOString() !== manifest.syncedAt
+    || !["bundled-payload", "local-plugin-source"].includes(manifest.source)
+    || !/^[a-f0-9]{64}$/.test(manifest.sourceHash || "")
+  ) {
+    return { entries: new Map(), issue: "manifest missing" };
+  }
+  const entries = new Map();
+  for (const entry of manifest.files) {
+    if (
+      !exactKeys(entry, ["path", "sha256"])
+      || typeof entry.path !== "string"
+      || !/^[a-f0-9]{64}$/.test(entry.sha256 || "")
+    ) {
+      return { entries, issue: "manifest entry invalid" };
+    }
+    const relative = entry.path.replaceAll("\\", "/");
+    if (
+      !relative
+      || path.posix.isAbsolute(relative)
+      || relative.split("/").some((segment) => !segment || segment === "." || segment === "..")
+      || entries.has(relative)
+    ) {
+      return { entries, issue: "manifest path invalid or duplicate" };
+    }
+    if (relative.split("/").includes("__pycache__") || /\.py[co]$/.test(relative)) {
+      return { entries, issue: "manifest contains Python bytecode" };
+    }
+    entries.set(relative, entry.sha256);
+  }
+  if (verifySourceHash) {
+    const aggregate = crypto
+      .createHash("sha256")
+      .update([...entries].map(([entryPath, hash]) => `${entryPath}:${hash}`).sort().join("\n"))
+      .digest("hex");
+    if (typeof manifest.sourceHash !== "string" || aggregate !== manifest.sourceHash) {
+      return { entries, issue: "manifest source hash mismatch" };
+    }
+  }
+  return { entries, issue: null };
+}
+
+function capturePayloadManifest(file) {
+  const root = path.dirname(path.resolve(file));
+  const relative = path.basename(file);
+  const captured = captureRegularFile(root, relative, {
+    maxFileBytes: MAX_PAYLOAD_MANIFEST_BYTES,
+    maxTotalBytes: MAX_PAYLOAD_MANIFEST_BYTES,
+  });
+  if (!captured.ok || !captured.record) return { ...captured, manifest: null };
+  try {
+    return {
+      ...captured,
+      manifest: parseJsonRejectingDuplicateKeys(captured.record.buffer.toString("utf8")),
+    };
+  } catch {
+    return {
+      ok: false,
+      failures: [`${relative}:invalid-json-or-duplicate-key`],
+      capture: null,
+      record: null,
+      manifest: null,
+    };
+  }
+}
+
+function readPayloadManifest(file) {
+  return capturePayloadManifest(file).manifest;
+}
+
+function capturePayloadInventory(pluginPath, options = {}) {
+  const manifestPath = path.join(pluginPath, "payload-version.json");
+  const manifestCapture = capturePayloadManifest(manifestPath);
+  if (!manifestCapture.ok || !manifestCapture.manifest || !manifestCapture.record) {
+    return { ok: false, failures: manifestCapture.failures || ["payload manifest capture failed"] };
+  }
+  const inspected = inspectManifest(manifestCapture.manifest, true);
+  const sourceInspection = inspectSkillPayload(pluginPath, manifestCapture.manifest, true);
+  if (inspected.issue || !sourceInspection.ok) {
+    return {
+      ok: false,
+      failures: [inspected.issue || "payload source verification failed"],
+    };
+  }
+
+  const maxFileBytes = options.maxFileBytes ?? MAX_PAYLOAD_FILE_BYTES;
+  const maxTotalBytes = options.maxTotalBytes ?? MAX_PAYLOAD_TOTAL_BYTES;
+  const capturedBytes = new Map();
+  const captures = [manifestCapture.capture];
+  let totalBytes = manifestCapture.record.buffer.length;
+  for (const [relative, expectedHash] of inspected.entries) {
+    const captured = captureRegularFile(pluginPath, relative, {
+      maxFileBytes,
+      maxTotalBytes: maxFileBytes,
+    });
+    if (!captured.ok || !captured.record) {
+      return { ok: false, failures: [`${relative}:capture-failed`] };
+    }
+    totalBytes += captured.record.buffer.length;
+    if (totalBytes > maxTotalBytes) {
+      return { ok: false, failures: ["payload aggregate too large"] };
+    }
+    if (crypto.createHash("sha256").update(captured.record.buffer).digest("hex") !== expectedHash) {
+      return { ok: false, failures: [`${relative}:hash-mismatch`] };
+    }
+    captures.push(captured.capture);
+    capturedBytes.set(relative, captured.record.buffer);
+  }
+  if (!captures.every((capture) => revalidateDescriptorCapture(capture))) {
+    return { ok: false, failures: ["payload capture identity changed"] };
+  }
+  return {
+    ok: true,
+    failures: [],
+    manifest: manifestCapture.manifest,
+    manifestBuffer: manifestCapture.record.buffer,
+    capturedBytes,
+    captures,
+    totalBytes,
+  };
+}
+
+function entryLabel(relativePath) {
+  const match = relativePath.match(/^skills\/([^/]+)\/(.+)$/);
+  return match ? { id: match[1], path: match[2] } : { id: "payload", path: relativePath };
+}
+
+function checkEntry(pluginPath, relativePath, expectedHash) {
+  const file = path.join(pluginPath, ...relativePath.split("/"));
+  const label = entryLabel(relativePath);
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch {
+    return { ...label, reason: "missing" };
+  }
+  if (!stat.isFile()) return { ...label, reason: "not regular" };
+  if (stat.size === 0 && path.posix.basename(relativePath) !== ".gitkeep") {
+    return { ...label, reason: "empty" };
+  }
+  try {
+    return sha256(file) === expectedHash ? null : { ...label, reason: "hash mismatch" };
+  } catch {
+    return { ...label, reason: "unreadable" };
+  }
+}
+
+function listPayloadEntries(root, readDirectory = fs.readdirSync) {
+  const results = [];
+  function visit(directory, prefix = "") {
+    for (const entry of readDirectory(directory, { withFileTypes: true })) {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        results.push(`${relative}/`);
+        visit(absolute, relative);
+      }
+      else results.push(relative);
+    }
+  }
+  try {
+    visit(root);
+  } catch {
+    return { entries: results, issue: "traversal failed" };
+  }
+  return { entries: results, issue: null };
+}
+
+function inspectSkillPayload(pluginPath, manifest, verifySourceHash = false, options = {}) {
+  const inspected = inspectManifest(manifest, verifySourceHash);
+  const failures = [];
+  const rootEntrypoints = new Set(requiredSkills.map((id) => `skills/${id}/SKILL.md`));
+  for (const id of requiredSkills) {
+    const prefix = `skills/${id}/`;
+    if (!inspected.entries.has(`${prefix}SKILL.md`)) {
+      failures.push({ id, path: "SKILL.md", reason: "manifest missing" });
+      continue;
+    }
+    const failure = checkEntry(pluginPath, `${prefix}SKILL.md`, inspected.entries.get(`${prefix}SKILL.md`));
+    if (failure) {
+      failures.push(failure);
+    }
+  }
+  for (const [entryPath, expectedHash] of inspected.entries) {
+    if (rootEntrypoints.has(entryPath)) continue;
+    const failure = checkEntry(pluginPath, entryPath, expectedHash);
+    if (failure) failures.push(failure);
+  }
+  const allowedUnlisted = new Set(["payload-version.json"]);
+  const allowedDirectories = new Set();
+  for (const entryPath of inspected.entries.keys()) {
+    const segments = entryPath.split("/");
+    for (let index = 1; index < segments.length; index += 1) {
+      allowedDirectories.add(`${segments.slice(0, index).join("/")}/`);
+    }
+  }
+  const traversal = listPayloadEntries(pluginPath, options.readDirectory);
+  for (const entryPath of traversal.entries) {
+    if (
+      inspected.entries.has(entryPath)
+      || allowedUnlisted.has(entryPath)
+      || allowedDirectories.has(entryPath)
+    ) continue;
+    failures.push({ ...entryLabel(entryPath), reason: "unexpected" });
+  }
+  if (traversal.issue) {
+    failures.push({ id: "payload", path: ".", reason: traversal.issue });
+  }
+  const canonical = inspectCanonicalFrontend(pluginPath);
+  if (!canonical.ok) {
+    failures.push({
+      id: "frontend-ui-ux",
+      path: "references/_canonical-corpus",
+      reason: "canonical verification failed",
+    });
+  }
+  return {
+    failures,
+    manifestIssue: inspected.issue,
+    ok: !inspected.issue && failures.length === 0,
+  };
+}
+
+function inspectCanonicalFrontend(pluginPath) {
+  return verifyCanonicalCorpus(path.join(
+    pluginPath,
+    "skills",
+    "frontend-ui-ux",
+    "references",
+    "_canonical-corpus",
+  ));
+}
+
+function scanPluginSkills(pluginPath, manifest, verifySourceHash = false) {
+  const inspection = inspectSkillPayload(pluginPath, manifest, verifySourceHash);
+  if (inspection.manifestIssue) return [];
+  const failed = new Set(inspection.failures.map((failure) => failure.id));
+  return requiredSkills.filter((id) => !failed.has(id));
+}
+
+function formatSkillPayload(inspection) {
+  if (inspection.ok) return "PASS";
+  if (inspection.manifestIssue) return `FAIL (${inspection.manifestIssue})`;
+  const entrypointFailures = inspection.failures.filter((failure) => failure.path === "SKILL.md");
+  const nestedFailures = inspection.failures.filter((failure) => failure.path !== "SKILL.md");
+  const groups = new Map();
+  for (const failure of entrypointFailures) {
+    const ids = groups.get(failure.reason) || [];
+    ids.push(failure.id);
+    groups.set(failure.reason, ids);
+  }
+  const messages = [
+    ...[...groups].map(([reason, ids]) => `${reason} ${ids.join(", ")}`),
+    ...nestedFailures.map((failure) => `${failure.id}/${failure.path} ${failure.reason}`),
+  ];
+  return `FAIL (${messages.join("; ")})`;
+}
+
+module.exports = {
+  MAX_PAYLOAD_FILE_BYTES,
+  MAX_PAYLOAD_MANIFEST_BYTES,
+  MAX_PAYLOAD_TOTAL_BYTES,
+  capturePayloadInventory,
+  capturePayloadManifest,
+  formatSkillPayload,
+  inspectCanonicalFrontend,
+  inspectSkillPayload,
+  readPayloadManifest,
+  requiredSkills,
+  scanPluginSkills,
+};