mulmoterminal 0.1.2 → 0.1.4

package/README.md

@@ -24,7 +24,17 @@ npm install -g mulmoterminal
 mulmoterminal
 ```
 
-Options: `--port <n>` (default 3456), `--no-open`, `--version`, `--help`.
+A global install isn't auto-updated, so on startup MulmoTerminal checks npm and
+prints a one-line notice when a newer version is available (`npm i -g mulmoterminal`
+to update). Disable with `MULMOTERMINAL_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`).
+
+Options: `--cwd <dir>` (working directory — relative paths allowed; defaults to the
+directory you run the command from), `--port <n>` (default 3456), `--no-open`,
+`--version`, `--help`.
+
+```bash
+npx mulmoterminal --cwd ./my-project   # work in a specific directory
+```
 
 The published package ships the server (run via `tsx`) plus the pre-built web UI;
 `npx mulmoterminal` checks for the `claude` CLI, picks a free port, starts the
@@ -118,7 +128,7 @@ the server runs without one.
 | ------------ | -------------- | ----------- |
 | `PORT`       | `3456`         | HTTP/WebSocket port. |
 | `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. |
-| `CLAUDE_CWD` | `$HOME`        | Working directory each `claude` PTY runs in. Determines which project's sessions the sidebar lists. **Must be an absolute path** — `~` is not expanded for values read from `.env`. |
+| `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions the sidebar lists. Via `npx mulmoterminal` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). |
 
 Example `.env` (gitignored):
 

package/bin/mulmoterminal.js

@@ -6,12 +6,13 @@
 // runs the server via tsx. Mirrors the mulmoclaude launcher.
 
 import { execSync, spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { get as httpGet } from "node:http";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { fetchLatestVersion, isNewerVersion } from "./update-check.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_DIR = join(__dirname, "..");
@@ -30,6 +31,21 @@ const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 const log = (msg) => console.log(`\x1b[36m[mulmoterminal]\x1b[0m ${msg}`);
 const error = (msg) => console.error(`\x1b[31m[mulmoterminal]\x1b[0m ${msg}`);
 
+// Non-blocking notice when a newer version is published — `npm i -g` never
+// auto-updates. Opt out via MULMOTERMINAL_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER.
+function checkForUpdate() {
+  if (process.env.MULMOTERMINAL_NO_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER) return;
+  fetchLatestVersion()
+    .then((latest) => {
+      if (latest && isNewerVersion(latest, VERSION)) {
+        log(`\x1b[33mUpdate available: ${VERSION} → ${latest}  ·  run: npm i -g mulmoterminal\x1b[0m`);
+      }
+    })
+    .catch(() => {
+      // best-effort; never disrupt startup
+    });
+}
+
 function claudeInstalled() {
   try {
     // Intentionally resolves `claude` from the user's PATH — detecting their
@@ -129,6 +145,29 @@ function parsePortArg(args) {
   return { requestedPort: parsed, portExplicit: true };
 }
 
+// Resolve the workspace directory claude runs in (and whose sessions the sidebar
+// lists). Precedence: --cwd (relative paths allowed) > CLAUDE_CWD env > the
+// directory npx was run from. Always returned absolute. An explicit --cwd that
+// isn't an existing directory is a hard error (catches typos before launch).
+function resolveCwd(args) {
+  const idx = args.indexOf("--cwd");
+  let flagValue;
+  if (idx !== -1) {
+    flagValue = args[idx + 1];
+    if (flagValue === undefined || flagValue.startsWith("-")) {
+      error("--cwd requires a directory path");
+      process.exit(1);
+    }
+  }
+  const chosen = flagValue ?? process.env.CLAUDE_CWD ?? ".";
+  const abs = resolve(process.cwd(), chosen);
+  if (idx !== -1 && (!existsSync(abs) || !statSync(abs).isDirectory())) {
+    error(`--cwd is not a directory: ${abs}`);
+    process.exit(1);
+  }
+  return abs;
+}
+
 async function choosePort(requested, explicit) {
   if (await isPortFree(requested)) return requested;
   if (explicit) {
@@ -149,12 +188,12 @@ async function choosePort(requested, explicit) {
 // the port was taken at bind time before it became ready — the caller then
 // retries on a fresh port. In every other case (clean shutdown, fatal error,
 // or the server simply running) the process exits with the server's code.
-function runServer(port, noOpen, onChild) {
-  return new Promise((resolve) => {
+function runServer(port, noOpen, cwd, onChild) {
+  return new Promise((resolveExit) => {
     log(`Starting MulmoTerminal on port ${port}...`);
     const server = spawn(process.execPath, ["--import", "tsx", SERVER_ENTRY], {
       cwd: PKG_DIR,
-      env: { ...process.env, NODE_ENV: "production", PORT: String(port) },
+      env: { ...process.env, NODE_ENV: "production", PORT: String(port), CLAUDE_CWD: cwd },
       stdio: "inherit",
     });
     onChild(server);
@@ -178,7 +217,7 @@ function runServer(port, noOpen, onChild) {
       // served — always retriable, regardless of what a probe to the port saw
       // (another process could have answered it). Other exits are terminal.
       if (code === PORT_IN_USE_EXIT_CODE) {
-        resolve();
+        resolveExit();
         return;
       }
       process.exit(code ?? 1);
@@ -194,6 +233,7 @@ async function main() {
 Usage: npx mulmoterminal [options]
 
 Options:
+  --cwd <dir>       Working directory claude runs in (default: current directory; relative paths allowed)
   --port <number>   Server port (default: ${DEFAULT_PORT}; a free port is chosen if it's busy)
   --no-open         Don't open the browser automatically
   --version         Show version
@@ -206,6 +246,8 @@ Options:
     return;
   }
 
+  checkForUpdate();
+
   if (!claudeInstalled()) {
     error("Claude Code CLI not found.");
     error("Install it first:  npm install -g @anthropic-ai/claude-code  &&  claude auth login");
@@ -220,6 +262,8 @@ Options:
 
   const { requestedPort, portExplicit } = parsePortArg(args);
   const noOpen = args.includes("--no-open");
+  const cwd = resolveCwd(args);
+  log(`Workspace: ${cwd}`);
 
   // Registered once; always targets the live child across bind-retries.
   let child = null;
@@ -235,7 +279,7 @@ Options:
   // second-guessed. `runServer` only returns when the port was raced.
   let port = await choosePort(requestedPort, portExplicit);
   for (let attempt = 0; attempt <= MAX_BIND_RETRIES; attempt++) {
-    await runServer(port, noOpen, (c) => {
+    await runServer(port, noOpen, cwd, (c) => {
       child = c;
     });
     if (portExplicit) {

package/bin/update-check.js

@@ -0,0 +1,37 @@
+// Update-check helpers for the launcher, split out so the version comparison is
+// unit-testable. Network calls are best-effort and never throw.
+
+const REGISTRY = (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/$/, "");
+
+// Best-effort latest-version lookup. Resolves null on any failure (offline,
+// timeout, non-OK, bad payload) so callers never block or break startup.
+export async function fetchLatestVersion(pkg = "mulmoterminal") {
+  try {
+    const res = await fetch(`${REGISTRY}/${pkg}/latest`, {
+      signal: AbortSignal.timeout(1500),
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// True if `latest` is a strictly newer major.minor.patch than `current`.
+// Pre-release suffixes are ignored and parts are compared numerically (so
+// 0.1.10 > 0.1.9, which a lexical compare would get wrong).
+export function isNewerVersion(latest, current) {
+  const parts = (v) =>
+    String(v)
+      .split("-")[0]
+      .split(".")
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const a = parts(latest);
+  const b = parts(current);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return false;
+}

package/bin/update-check.spec.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { isNewerVersion, fetchLatestVersion } from "./update-check.js";
+
+describe("isNewerVersion", () => {
+  const cases: [string, string, boolean][] = [
+    ["0.1.3", "0.1.0", true],
+    ["0.2.0", "0.1.9", true],
+    ["1.0.0", "0.9.9", true],
+    ["0.1.10", "0.1.9", true], // numeric, not lexical (the bug a string compare hits)
+    ["0.1.3", "0.1.3", false],
+    ["0.1.0", "0.1.3", false],
+    ["0.9.9", "1.0.0", false],
+    ["0.1.4-beta.1", "0.1.3", true], // pre-release suffix ignored on the core
+    ["0.1.3", "0.1.3-beta.1", false], // equal core → not newer
+  ];
+  it.each(cases)("isNewerVersion(%s, %s) === %s", (latest, current, expected) => {
+    expect(isNewerVersion(latest, current)).toBe(expected);
+  });
+});
+
+describe("fetchLatestVersion", () => {
+  const stubFetch = (impl: () => Promise<unknown>) => vi.stubGlobal("fetch", vi.fn(impl));
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("returns the version from a 200 response", async () => {
+    stubFetch(async () => ({ ok: true, json: async () => ({ version: "1.2.3" }) }));
+    expect(await fetchLatestVersion()).toBe("1.2.3");
+  });
+
+  it("returns null on a non-OK response", async () => {
+    stubFetch(async () => ({ ok: false, json: async () => ({}) }));
+    expect(await fetchLatestVersion()).toBeNull();
+  });
+
+  it("returns null when fetch rejects (offline / timeout)", async () => {
+    stubFetch(async () => {
+      throw new Error("offline");
+    });
+    expect(await fetchLatestVersion()).toBeNull();
+  });
+
+  it("returns null when the payload has no version string", async () => {
+    stubFetch(async () => ({ ok: true, json: async () => ({ name: "mulmoterminal" }) }));
+    expect(await fetchLatestVersion()).toBeNull();
+  });
+});