@holt-os/holt 0.8.2 → 0.8.3

package/README.md

@@ -10,10 +10,23 @@ Holt is an open-source, self-hosted personal agent OS. Clone it, pick your skill
 
 ---
 
-## Quickstart
+## Install
+
+With Homebrew (installs Node for you, so you do not need npm first):
+
+```bash
+brew install holt-os/tap/holt
+```
+
+Or with npm, if you already have Node:
 
 ```bash
 npm install -g @holt-os/holt
+```
+
+## Quickstart
+
+```bash
 cd ~/where-you-want-to-work
 holt init      # trust this folder, choose and install brains, sign in, set defaults
 holt chat      # start talking (or use your custom command, e.g. `ai`)

package/dist/cli.js

@@ -324,8 +324,29 @@ ${END}`;
     return { ok: false, kind: "none", file, immediate: false, message: `Could not write ${file}: ${e.message}` };
   }
 }
+function isValidAliasName(name) {
+  return /^[A-Za-z_][A-Za-z0-9_-]{0,31}$/.test(name);
+}
 function installAlias(name) {
+  if (!isValidAliasName(name)) {
+    return {
+      ok: false,
+      kind: "none",
+      file: "",
+      immediate: false,
+      message: `"${name}" is not a valid launch command. Use a single word: a letter or _ then letters, digits, _ or - (max 32).`
+    };
+  }
   removeAlias();
+  if (process.platform !== "win32" && isInstalled(name)) {
+    return {
+      ok: false,
+      kind: "none",
+      file: "",
+      immediate: false,
+      message: `"${name}" is already a command on your PATH. Pick another word.`
+    };
+  }
   if (process.platform !== "win32") {
     const binDir = launcherBinDir();
     if (binDir) {
@@ -480,9 +501,10 @@ function appendTurn(t) {
 }
 function clearMemory() {
   if (existsSync4(memPath())) rmSync2(memPath());
+  if (existsSync4(factsMdPath())) rmSync2(factsMdPath());
 }
 function normalizeFact(s) {
-  return s.toLowerCase().replace(/\s+/g, " ").trim().replace(/[.,;:!?]+$/, "");
+  return (s || "").toLowerCase().replace(/\s+/g, " ").trim().replace(/[.,;:!?]+$/, "");
 }
 var FACTS_HEADER = "# Holt facts\n\nDistilled memories for this folder. Safe to edit by hand.\n";
 async function saveFact(content, session) {
@@ -550,7 +572,7 @@ function cosine(a, b) {
 }
 function tokens(s) {
   return new Set(
-    s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2)
+    (s || "").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2)
   );
 }
 function keywordScore(q, text) {
@@ -612,7 +634,7 @@ function loadTelegramConfig() {
   if (!existsSync5(path)) return null;
   try {
     const raw = JSON.parse(readFileSync5(path, "utf8"));
-    if (typeof raw.token !== "string" || typeof raw.allowedChatId !== "number") return null;
+    if (typeof raw.token !== "string" || typeof raw.allowedChatId !== "number" || raw.allowedChatId === 0) return null;
     return { token: raw.token, allowedChatId: raw.allowedChatId };
   } catch {
     return null;
@@ -674,11 +696,11 @@ async function sendMessage(text, chatId) {
   }
   return allOk;
 }
-async function getUpdates(offset) {
-  const cfg = loadTelegramConfig();
-  if (!cfg) return [];
+async function getUpdates(offset, tokenOverride) {
+  const token = tokenOverride ?? loadTelegramConfig()?.token;
+  if (!token) return [];
   const timeoutSec = 30;
-  const url = buildGetUpdatesUrl(cfg.token, offset, timeoutSec);
+  const url = buildGetUpdatesUrl(token, offset, timeoutSec);
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), (timeoutSec + 10) * 1e3);
   try {
@@ -1062,9 +1084,8 @@ async function setupTelegram(ask) {
   const mode = (await ask("\n  Auto-detect from a message you just sent? [Y/n] ") ?? "").trim().toLowerCase();
   let allowedChatId = null;
   if (mode === "" || mode === "y" || mode === "yes") {
-    saveTelegramConfig({ token, allowedChatId: 0 });
     console.log(c.dim("\n  Checking for a recent message..."));
-    const updates = await getUpdates(0);
+    const updates = await getUpdates(0, token);
     allowedChatId = latestChatId(updates);
     if (allowedChatId === null) {
       console.log(c.red("  Did not find a recent message."));
@@ -1586,7 +1607,7 @@ async function extractAndSaveFacts(active, cfg, history, session) {
 
 // src/output.ts
 import { writeFileSync as writeFileSync6 } from "fs";
-import { join as join7 } from "path";
+import { join as join7, isAbsolute } from "path";
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
@@ -1597,8 +1618,12 @@ function renderInline(text) {
     return `\0${codes.length - 1}\0`;
   });
   s = escapeHtml(s);
-  s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, label, url) => {
-    const safe = url.replace(/"/g, "%22");
+  s = s.replace(/\[([^\]]+)\]\((\S*?(?:\([^)\s]*\)[^)\s]*)*)\)/g, (_m, label, url) => {
+    const trimmed = url.trim();
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+    const safeScheme = !scheme || /^(https?|mailto)$/i.test(scheme[1]);
+    if (!safeScheme) return label;
+    const safe = trimmed.replace(/"/g, "%22");
     return `<a href="${safe}">${label}</a>`;
   });
   s = s.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
@@ -1718,6 +1743,9 @@ function saveReply(reply, format, name) {
   const ext = format === "html" ? ".html" : ".md";
   let base = (name ?? "").trim();
   if (!base) base = `holt-reply-${timestamp()}`;
+  if (isAbsolute(base) || /[\\/]/.test(base) || base === "." || base === "..") {
+    throw new Error('name must be a plain file name in this folder (no "/", "\\", or "..").');
+  }
   if (!/\.[a-z0-9]+$/i.test(base)) base += ext;
   const path = join7(process.cwd(), base);
   writeFileSync6(path, renderReply(reply, format), "utf8");
@@ -1877,15 +1905,17 @@ async function chat() {
         const cliEnabled = BRAIN_IDS.filter((id) => cfg.brains[id].enabled);
         const apiIds = cfg.apiBrains.map((a) => a.id);
         const all = [...cliEnabled, ...apiIds];
-        if (arg && all.includes(arg)) {
-          const next = resolveActive2(cfg, arg);
+        const rawArg = parts[1] || "";
+        const match = all.find((id) => id.toLowerCase() === rawArg.toLowerCase());
+        if (rawArg && match) {
+          const next = resolveActive2(cfg, match);
           if (next) {
             active = next;
             const turns = Math.floor(history.length / 2);
             console.log(c.green(`  switched to ${active.label}. Context kept (${turns} turn${turns === 1 ? "" : "s"}).`));
           }
-        } else if (arg) {
-          console.log(c.dim(`  "${arg}" is not available. Available: ${all.join(", ") || "none"}`));
+        } else if (rawArg) {
+          console.log(c.dim(`  "${rawArg}" is not available. Available: ${all.join(", ") || "none"}`));
         } else {
           const cfgRef = cfg;
           const activeId = active.id;
@@ -1958,9 +1988,16 @@ async function chat() {
 async function login(which) {
   const id = (which || "").toLowerCase();
   if (!BRAIN_IDS.includes(id)) {
-    console.log(c.dim(`
+    if (which) {
+      console.error(`
+  Unknown brain "${which}". Use one of: ${BRAIN_IDS.join(", ")}
+`);
+      process.exitCode = 1;
+    } else {
+      console.log(c.dim(`
   Usage: holt login <${BRAIN_IDS.join("|")}>
 `));
+    }
     return;
   }
   const s = BRAIN_SETUP[id];
@@ -2046,6 +2083,14 @@ async function memoryCmd(sub, rest = []) {
     close();
     return;
   }
+  if (action && !["clear", "embed", "facts", "search"].includes(action)) {
+    console.error(`
+  Unknown memory subcommand: "${sub}". Use: search <query> | facts | embed | clear
+`);
+    process.exitCode = 1;
+    close();
+    return;
+  }
   const s = memStats();
   const embedOk = await embeddingsAvailable();
   const sessions = new Set(loadTurns().map((t) => t.session)).size;
@@ -2170,9 +2215,10 @@ function cmdShow(name) {
   }
   const loaded = loadSkill(name);
   if (!loaded) {
-    console.log(c.dim(`
+    console.error(c.dim(`
   No skill named "${sanitizeName(name)}". Try "holt skill list".
 `));
+    process.exitCode = 1;
     return;
   }
   const { skill, body } = loaded;
@@ -2192,9 +2238,10 @@ function cmdCreate(name, global) {
   const scope = global ? "global" : "workspace";
   const dir = join8(skillsRoot(scope), clean);
   if (existsSync8(dir)) {
-    console.log(c.red(`
+    console.error(c.red(`
   A ${scope} skill named "${clean}" already exists.`));
-    console.log(c.dim("  " + dir + "\n"));
+    console.error(c.dim("  " + dir + "\n"));
+    process.exitCode = 1;
     return;
   }
   mkdirSync6(dir, { recursive: true });
@@ -2219,22 +2266,25 @@ function cmdAdd(source, global) {
   Cloning ${source} ...`));
       const res = spawnSync2("git", ["clone", "--depth", "1", source, tempDir], { stdio: "ignore" });
       if (res.status !== 0) {
-        console.log(c.red("  Clone failed. Check the URL and that git is installed.\n"));
+        console.error(c.red("  Clone failed. Check the URL and that git is installed.\n"));
+        process.exitCode = 1;
         return;
       }
       fetched = tempDir;
     } else {
       fetched = resolve(source);
       if (!existsSync8(fetched)) {
-        console.log(c.red(`
+        console.error(c.red(`
   No such path: ${fetched}
 `));
+        process.exitCode = 1;
         return;
       }
     }
     const skillDir = findSkillDir(fetched);
     if (!skillDir) {
-      console.log(c.red("\n  Could not find a SKILL.md at the source root or in a single subfolder.\n"));
+      console.error(c.red("\n  Could not find a SKILL.md at the source root or in a single subfolder.\n"));
+      process.exitCode = 1;
       return;
     }
     let skillName = "";
@@ -2246,14 +2296,16 @@ function cmdAdd(source, global) {
     }
     if (!skillName) skillName = sanitizeName(skillDir.split(/[\\/]/).pop() || "");
     if (!skillName) {
-      console.log(c.red("\n  Could not determine a valid skill name.\n"));
+      console.error(c.red("\n  Could not determine a valid skill name.\n"));
+      process.exitCode = 1;
       return;
     }
     const dest = join8(skillsRoot(scope), skillName);
     if (existsSync8(dest)) {
-      console.log(c.red(`
+      console.error(c.red(`
   A ${scope} skill named "${skillName}" already exists.`));
-      console.log(c.dim("  " + dest + "\n"));
+      console.error(c.dim("  " + dest + "\n"));
+      process.exitCode = 1;
       return;
     }
     mkdirSync6(skillsRoot(scope), { recursive: true });
@@ -2282,9 +2334,10 @@ async function cmdRemove(name, ask) {
   const globalDir = join8(skillsRoot("global"), clean);
   const target = existsSync8(wsDir) ? wsDir : existsSync8(globalDir) ? globalDir : "";
   if (!target) {
-    console.log(c.dim(`
+    console.error(c.dim(`
   No skill named "${clean}" found.
 `));
+    process.exitCode = 1;
     return;
   }
   const scope = target === wsDir ? "workspace" : "global";
@@ -2330,6 +2383,7 @@ async function skillCmd(sub, rest = []) {
         await cmdRemove(args[0], ask);
         break;
       default:
+        if (action) process.exitCode = 1;
         usage();
     }
   } finally {
@@ -2504,7 +2558,7 @@ function buildGraph(turns) {
   return { nodes, edges };
 }
 function escapeForScript(json) {
-  return json.replace(/<\/(script)/gi, "<\\/$1").replace(/<!--/g, "<\\!--");
+  return json.replace(/<\/(script)/gi, "<\\/$1").replace(/<!--/g, "<\\u0021--");
 }
 function escapeHtml2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -2617,7 +2671,14 @@ function renderGraphHtml(graph2, meta) {
 <script>
 (function () {
   "use strict";
-  var DATA = JSON.parse(document.getElementById("graph-data").textContent);
+  var DATA;
+  try {
+    DATA = JSON.parse(document.getElementById("graph-data").textContent);
+  } catch (e) {
+    document.getElementById("empty").textContent = "Could not read the graph data.";
+    document.getElementById("empty").style.display = "flex";
+    return;
+  }
   var nodes = DATA.nodes || [];
   var edges = DATA.edges || [];
 
@@ -3177,6 +3238,7 @@ function runMcpServer(opts) {
 
 // src/mcp/tools.ts
 var MCP_SESSION = "__mcp__";
+var MCP_RECALL_SESSION = "__mcp_recall__";
 function holtTools() {
   return [
     {
@@ -3195,7 +3257,7 @@ function holtTools() {
           const query = String(args.query || "").trim();
           if (!query) return "Provide a query to recall.";
           const k = Number(args.k) || 5;
-          const hits = await recall(query, MCP_SESSION, k);
+          const hits = await recall(query, MCP_RECALL_SESSION, k);
           if (hits.length === 0) return "No relevant memory found.";
           const lines = hits.map(
             (h) => `${h.score.toFixed(2)}  (${h.turn.role})  ${h.turn.content.replace(/\s+/g, " ").trim()}`
@@ -3287,6 +3349,9 @@ function holtTools() {
   ];
 }
 
+// src/version.ts
+var VERSION = "0.8.3";
+
 // src/commands/mcp.ts
 function printSetup() {
   const config = JSON.stringify(
@@ -3315,10 +3380,15 @@ async function mcp(sub, rest = []) {
     printSetup();
     return;
   }
+  if (sub !== void 0) {
+    console.error(`Unknown mcp subcommand: "${sub}". Use "holt mcp" to serve, or "holt mcp setup".`);
+    process.exitCode = 1;
+    return;
+  }
   try {
     if (!isTrusted()) trustDir();
     console.error("Holt MCP: serving memory for " + workspace());
-    await runMcpServer({ name: "holt", version: "0.7.0", tools: holtTools() });
+    await runMcpServer({ name: "holt", version: VERSION, tools: holtTools() });
   } catch (err2) {
     console.error("Holt MCP failed: " + (err2 instanceof Error ? err2.message : String(err2)));
     process.exitCode = 1;
@@ -3403,21 +3473,27 @@ async function run(args) {
       process.stdout.write(ch);
     }
   });
+  if (!result.ok) {
+    if (streamed) process.stdout.write("\n");
+    process.stderr.write(c.red(result.text) + "\n");
+    process.exitCode = 1;
+    return;
+  }
   if (!p.quiet && !streamed) {
     process.stdout.write(result.text);
   }
   if (!p.quiet && (streamed || result.text) && !result.text.endsWith("\n")) {
     process.stdout.write("\n");
   }
-  if (!result.ok) {
-    process.stderr.write(c.red(result.text) + "\n");
-    process.exitCode = 1;
-    return;
-  }
   if (p.out) {
     const target = resolve3(process.cwd(), p.out);
-    writeFileSync9(target, result.text, "utf8");
-    process.stderr.write(c.dim(`saved to ${target}`) + "\n");
+    try {
+      writeFileSync9(target, result.text, "utf8");
+      process.stderr.write(c.dim(`saved to ${target}`) + "\n");
+    } catch (e) {
+      process.stderr.write(c.red(`Could not write ${target}: ${e.message}`) + "\n");
+      process.exitCode = 1;
+    }
   }
 }
 
@@ -3619,12 +3695,14 @@ async function addCmd(rest) {
   const { task, when, opts } = parseAdd(rest);
   if (!task || !when) {
     console.log(c.dim('\n  Usage: holt schedule add "<task>" <HH:MM> [--name <n>] [--notify] [--brain <id>]\n'));
+    process.exitCode = 1;
     return;
   }
   try {
     parseWhen(when);
   } catch (e) {
-    console.log("\n  " + c.red(e.message) + "\n");
+    console.error("\n  " + c.red(e.message) + "\n");
+    process.exitCode = 1;
     return;
   }
   const ws = workspace();
@@ -3689,6 +3767,7 @@ function removeCmd(rest) {
   const id = rest[0];
   if (!id) {
     console.log(c.dim("\n  Usage: holt schedule remove <id>   (see ids with: holt schedule list)\n"));
+    process.exitCode = 1;
     return;
   }
   const before = loadJobs();
@@ -3697,9 +3776,12 @@ function removeCmd(rest) {
   if (process.platform === "darwin") removeDarwin(id);
   else if (process.platform === "linux") removeLinux(id);
   if (existed) console.log("\n" + c.green(`  Removed schedule ${id}.`) + "\n");
-  else console.log(c.dim(`
+  else {
+    console.error(c.dim(`
   No schedule with id ${id}. Nothing to remove.
 `));
+    process.exitCode = 1;
+  }
 }
 function usage2() {
   console.log("\n" + c.accent("holt schedule") + c.dim("  run a task automatically on a timer"));
@@ -3714,6 +3796,7 @@ async function schedule(sub, rest = []) {
     return;
   }
   if (action !== "add" && action !== "remove" && action !== "rm") {
+    if (action) process.exitCode = 1;
     usage2();
     return;
   }
@@ -3768,7 +3851,6 @@ function readStdin() {
 }
 
 // src/cli.ts
-var VERSION = "0.8.2";
 var BANNER = `
   \u2588\u2588\u2557  \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
   \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551  \u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D
@@ -3857,9 +3939,9 @@ async function main() {
       await notify(process.argv.slice(3));
       break;
     default:
-      console.log(`
+      console.error(`
   Unknown command: "${cmd}"`);
-      console.log(`  Run "holt help" for usage.
+      console.error(`  Run "holt help" for usage.
 `);
       process.exitCode = 1;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",