kablan 0.9.1 → 0.9.3

package/README.md

@@ -28,6 +28,11 @@ window — and opens your browser. Output goes to `~/Library/Logs/Kablan/kablan.
 Because the bundle is assembled on your machine rather than downloaded, macOS does not quarantine
 it: no "unidentified developer" prompt, and nothing to notarise.
 
+Installing stops every copy of Kablan that is already running first — a surviving process keeps
+serving the version it started with, which makes an update look like it did nothing. What it
+stopped is printed, and appended to `~/Library/Logs/Kablan/install.log`. A server you built
+yourself is left alone.
+
 - Update: `npx kablan@latest --install`
 - Remove: `npx kablan --uninstall` (cached binaries stay in `~/.kablan/bin`)
 

package/bin/cli.js

@@ -6,6 +6,7 @@ const path = require("path");
 const fs = require("fs");
 const { ensureBinary, BINARY_TAG, CACHE_DIR, LOCAL_DEV_MODE, LOCAL_DIST_DIR, getLatestVersion } = require("./download");
 const { installMacApp, uninstallMacApp, appDir } = require("./install-app");
+const { createInstallLogger, installLogPath } = require("./install-log");
 
 const CLI_VERSION = require("../package.json").version;
 
@@ -142,6 +143,19 @@ async function extractAndRun(baseName, launch) {
   return launch(binPath);
 }
 
+/**
+ * One line saying what was stopped, so the terminal and the log both show whether the update
+ * actually displaced anything — the failure this reporting exists to catch is an update that
+ * leaves the old version serving and says nothing.
+ */
+function summariseStopped(stopped) {
+  if (!stopped || stopped.length === 0) return "Stopped 0 running processes";
+  const detail = stopped
+    .map((p) => `${p.kind} ${p.version || "(unknown version)"} pid ${p.pid} via ${p.signal}`)
+    .join(", ");
+  return `Stopped ${stopped.length} running process${stopped.length === 1 ? "" : "es"}: ${detail}`;
+}
+
 async function main() {
   fs.mkdirSync(versionCacheDir, { recursive: true });
 
@@ -152,22 +166,25 @@ async function main() {
   // Kablan first: the swap would otherwise leave the old process serving, and the update would
   // look like it had not happened.
   if (args.includes("--uninstall")) {
-    const { app: removed, stoppedPid } = uninstallMacApp();
-    if (stoppedPid) console.log(`Stopped the running Kablan (pid ${stoppedPid})`);
-    console.log(removed ? `Removed ${removed}` : `Nothing installed at ${appDir()}`);
+    const log = createInstallLogger();
+    log(`Uninstalling (wrapper ${CLI_VERSION})`);
+    const { app: removed, stopped } = uninstallMacApp(log);
+    log(summariseStopped(stopped));
+    log(removed ? `Removed ${removed}` : `Nothing installed at ${appDir()}`);
     console.log("Cached binaries are still in ~/.kablan/bin; delete that to reclaim the space.");
     return;
   }
 
   if (args.includes("--install")) {
     await extractAndRun("kablan", (bin) => {
-      const { app, stoppedPid } = installMacApp(bin, CLI_VERSION);
-      if (stoppedPid) {
-        console.log(`\nStopped the running Kablan (pid ${stoppedPid}) so this version replaces it`);
-      }
-      console.log(`\nInstalled ${app}`);
-      console.log("Open it from Launchpad or Spotlight — it starts Kablan in the background");
+      const log = createInstallLogger();
+      log(`Installing ${CLI_VERSION}`);
+      const { app, stopped } = installMacApp(bin, CLI_VERSION, log);
+      log(summariseStopped(stopped));
+      log(`Installed ${app}`);
+      console.log("\nOpen it from Launchpad or Spotlight — it starts Kablan in the background");
       console.log("and opens your browser. Logs: ~/Library/Logs/Kablan/kablan.log");
+      console.log(`Install log: ${installLogPath()}`);
       console.log("\nUpdate with `npx kablan@latest --install`, remove with `npx kablan --uninstall`.");
     });
     return;
@@ -214,10 +231,15 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  console.error("Fatal error:", err.message);
-  if (process.env.KABLAN_DEBUG) {
-    console.error(err.stack);
-  }
-  process.exit(1);
-});
+// Only when run as a command. Requiring this file — the tests do — must not start Kablan.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error("Fatal error:", err.message);
+    if (process.env.KABLAN_DEBUG) {
+      console.error(err.stack);
+    }
+    process.exit(1);
+  });
+}
+
+module.exports = { summariseStopped };

package/bin/install-app.js

@@ -113,92 +113,163 @@ function infoPlist(version) {
 
 
 /**
- * Stop a Kablan that is already running, and say whether one was.
+ * Stops every Kablan server this installer manages, and says what it did.
  *
- * Replacing the bundle under a live process does nothing to that process: it keeps serving, the
- * launcher finds its port file and simply opens a browser at it, and the update looks like it
- * failed — the app still reports the version it was started with. So the install stops it first.
+ * The version is baked into the running process, so a copy that survives an update keeps serving
+ * the old build — the update looks like it silently failed. This used to read
+ * `$TMPDIR/kablan/kablan.port` and stop whoever held that port, which turned out to be one slot
+ * shared by every instance: a second server (a release build run from a checkout, say)
+ * overwrites it, and the installer then goes looking at the wrong port and stops nothing while
+ * the real app keeps running. That is a silent wrong answer, so the port file is no longer the
+ * handle.
  *
- * The port file is the only handle we have on it. Whoever is listening on that port has to look
- * like Kablan before it is signalled, because a stale port file plus a recycled port would
- * otherwise point at some unrelated process. SIGTERM first so the server can close its database
- * cleanly; SIGKILL only if it is still there after a grace period.
+ * Instead every process is examined and the ones that are ours are stopped — all of them, not
+ * the first. "Ours" means the executable lives in a directory this CLI owns: the version cache
+ * under ~/.kablan/bin, or the app bundle it builds. A server someone compiled themselves is
+ * deliberately left alone: it is not what an update replaces.
  *
- * @returns the pid stopped, or null when nothing was running
+ * SIGTERM first, so the server closes its database cleanly; SIGKILL only for one that outstays
+ * the grace period.
+ *
+ * @param {object} [deps] seams for the tests: every call to the outside world goes through one
+ * @returns {{stopped: Array<{pid: number, kind: string, version: string|null, signal: string}>,
+ *            skipped: Array<{pid: number, reason: string}>}}
  */
-function stopRunningApp() {
-  const bin = APP_NAME.toLowerCase();
-  const tmp = process.env.TMPDIR || "/tmp";
-  const portFile = path.join(tmp, bin, `${bin}.port`);
-
-  let port;
-  try {
-    port = fs.readFileSync(portFile, "utf8").trim();
-  } catch {
-    return null;
-  }
-  if (!/^\d+$/.test(port)) return null;
-
-  let pids;
-  try {
-    pids = execFileSync("/usr/sbin/lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    })
-      .split("\n")
-      .map((line) => line.trim())
-      .filter(Boolean);
-  } catch {
-    // Nothing listening: the port file outlived the process it described.
-    return null;
-  }
-
-  for (const pid of pids) {
-    let command = "";
-    try {
-      command = execFileSync("/bin/ps", ["-o", "command=", "-p", pid], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      }).trim();
-    } catch {
+function stopRunningApps(deps = {}) {
+  const {
+    listProcesses = defaultListProcesses,
+    kill = (pid, signal) => process.kill(pid, signal),
+    alive = (pid) => {
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    sleep = () => execFileSync("/bin/sleep", ["0.2"]),
+    now = () => Date.now(),
+    graceMs = 5000,
+    selfPid = process.pid,
+    parentPid = process.ppid,
+    log = () => {},
+  } = deps;
+
+  const stopped = [];
+  const skipped = [];
+
+  for (const { pid, command } of listProcesses()) {
+    const kind = classify(command);
+    if (!kind) continue;
+
+    // Signalling ourselves or the npx wrapper that spawned us would end the install midway.
+    if (pid === selfPid || pid === parentPid) {
+      skipped.push({ pid, reason: "self" });
       continue;
     }
-    // Ours: either a cached release binary or the one inside the bundle.
-    if (!command.includes(`.${bin}/bin/`) && !command.includes(`${bin}-server`)) continue;
+
+    const version = versionFromPath(command);
+    log(`Stopping ${kind}${version ? ` ${version}` : ""} (pid ${pid})`);
 
     try {
-      process.kill(Number(pid), "SIGTERM");
+      kill(pid, "SIGTERM");
     } catch {
+      // Gone between listing and signalling, or not ours to signal.
+      skipped.push({ pid, reason: "could not signal" });
       continue;
     }
 
-    // Give it a moment to close its database before resorting to SIGKILL.
-    const deadline = Date.now() + 5000;
-    while (Date.now() < deadline) {
-      try {
-        process.kill(Number(pid), 0);
-      } catch {
-        return pid; // gone
+    let signal = "SIGTERM";
+    const deadline = now() + graceMs;
+    while (alive(pid)) {
+      if (now() >= deadline) {
+        try {
+          kill(pid, "SIGKILL");
+          signal = "SIGKILL";
+          log(`  pid ${pid} ignored SIGTERM for ${graceMs / 1000}s; sent SIGKILL`);
+        } catch {
+          // Raced us to exit.
+        }
+        break;
       }
-      execFileSync("/bin/sleep", ["0.2"]);
-    }
-    try {
-      process.kill(Number(pid), "SIGKILL");
-    } catch {
-      // Raced us to exit.
+      sleep();
     }
-    return pid;
+
+    stopped.push({ pid, kind, version, signal });
   }
 
+  return { stopped, skipped };
+}
+
+/**
+ * Is this command line one of ours, and which kind? Anything else returns null and is left
+ * running — including a server built from a checkout, which no update of ours replaces.
+ *
+ * Only the executable is examined, never the arguments. `ps` prints the whole command line, so a
+ * shell that launched a server, a `tail` on its log, or an editor with the path open all carry
+ * our directory in their arguments; matching anywhere in the line would signal them.
+ */
+function classify(command) {
+  const bin = APP_NAME.toLowerCase();
+  const executable = executableOf(command);
+  if (executable.includes(`/.${bin}/bin/`)) {
+    return executable.endsWith(`${bin}-mcp`) ? "MCP server" : "server";
+  }
+  if (executable.includes(`/${APP_NAME}.app/Contents/MacOS/`)) return "installed app";
   return null;
 }
 
+/**
+ * The executable out of a `ps` command line — everything up to the first space.
+ *
+ * A path containing a space would be cut short and so not recognised as ours; the alternative,
+ * matching the whole line, mistakes every process that merely mentions the path for a server,
+ * and signalling the wrong process is the worse failure.
+ */
+function executableOf(command) {
+  const space = command.indexOf(" ");
+  return space === -1 ? command : command.slice(0, space);
+}
+
+/** ~/.kablan/bin/v0.9.1/macos-arm64/kablan -> "v0.9.1". Best effort; null when the path differs. */
+function versionFromPath(command) {
+  const match = command.match(/\/\.?[a-z]+\/bin\/(v[\d.]+)\//);
+  return match ? match[1] : null;
+}
+
+/** Every process on the machine, as {pid, command}. */
+function defaultListProcesses() {
+  let out = "";
+  try {
+    out = execFileSync("/bin/ps", ["-axo", "pid=,command="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 8 * 1024 * 1024,
+    });
+  } catch {
+    return [];
+  }
+  return out
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const space = line.indexOf(" ");
+      if (space === -1) return null;
+      const pid = Number(line.slice(0, space));
+      if (!Number.isInteger(pid)) return null;
+      return { pid, command: line.slice(space + 1).trim() };
+    })
+    .filter(Boolean);
+}
+
 /**
  * @param binPath  the extracted server binary to install
  * @param version  the wrapper's version, shown in Finder's Get Info
- * @returns {{ app: string, stoppedPid: string | null }}
+ * @param log      where progress goes; the caller tees this to the console and a file
+ * @returns {{ app: string, stopped: Array<object> }}
  */
-function installMacApp(binPath, version) {
+function installMacApp(binPath, version, log = () => {}) {
   if (process.platform !== "darwin") {
     throw new Error(
       `--install builds a macOS app bundle and this is ${process.platform}.\n` +
@@ -208,7 +279,8 @@ function installMacApp(binPath, version) {
 
   // Before anything is replaced: a running copy would survive the swap and keep serving the
   // version it started with.
-  const stoppedPid = stopRunningApp();
+  const { stopped } = stopRunningApps({ log });
+  if (stopped.length === 0) log("No running Kablan found; nothing to stop");
 
   const app = appDir();
   const macos = path.join(app, "Contents", "MacOS");
@@ -247,16 +319,25 @@ function installMacApp(binPath, version) {
     // Cosmetic only — the app works either way.
   }
 
-  return { app, stoppedPid };
+  return { app, stopped };
 }
 
-function uninstallMacApp() {
+function uninstallMacApp(log = () => {}) {
   // Removing the bundle from under a running server leaves it running with no way back to it.
-  const stoppedPid = stopRunningApp();
+  const { stopped } = stopRunningApps({ log });
   const app = appDir();
-  if (!fs.existsSync(app)) return { app: null, stoppedPid };
+  if (!fs.existsSync(app)) return { app: null, stopped };
   fs.rmSync(app, { recursive: true, force: true });
-  return { app, stoppedPid };
+  return { app, stopped };
 }
 
-module.exports = { installMacApp, uninstallMacApp, stopRunningApp, appDir, APP_NAME };
+module.exports = {
+  installMacApp,
+  uninstallMacApp,
+  stopRunningApps,
+  classify,
+  executableOf,
+  versionFromPath,
+  appDir,
+  APP_NAME,
+};

package/bin/install-log.js

@@ -0,0 +1,48 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+/**
+ * The record of what an install did.
+ *
+ * An update that goes wrong is quiet — you find out later, when the app reports a version you
+ * thought you had replaced, and by then the terminal that ran it is long gone. So every line the
+ * installer prints is also appended here, with a timestamp, next to the app's own log.
+ */
+
+function logDir() {
+  return path.join(os.homedir(), "Library", "Logs", "Kablan");
+}
+
+function installLogPath() {
+  return path.join(logDir(), "install.log");
+}
+
+/**
+ * A `log(line)` that prints and appends. Logging is never the reason an install fails: if the
+ * file cannot be written the line still reaches the terminal.
+ *
+ * @param {object} [deps] seams for the tests
+ */
+function createInstallLogger(deps = {}) {
+  const {
+    print = (line) => console.log(line),
+    file = installLogPath(),
+    appendFile = (target, text) => {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.appendFileSync(target, text);
+    },
+    stamp = () => new Date().toISOString(),
+  } = deps;
+
+  return function log(line) {
+    print(line);
+    try {
+      appendFile(file, `${stamp()} ${line}\n`);
+    } catch {
+      // A read-only home directory is not a reason to abandon the update.
+    }
+  };
+}
+
+module.exports = { createInstallLogger, installLogPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kablan",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "NPX wrapper around the Kablan server and its MCP task server",
   "license": "Apache-2.0",
   "author": "Shaked Amar",
@@ -33,5 +33,8 @@
   "dependencies": {
     "adm-zip": "^0.5.16"
   },
-  "private": false
+  "private": false,
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  }
 }