lavish-axi 0.1.16 → 0.1.18

package/README.md

@@ -35,7 +35,7 @@ Lavish Editor opens agent-generated HTML files in a local browser, lets you pinp
 
 - **Local only** - Work with your local HTML artifacts with a local CLI. Zero cloud dependency.
 - **Human-AI collaboration** - Annotate elements, selected text ranges, and send messages to the agent without leaving Lavish Editor.
-- **Battery included** - Lavish Editor teaches your agent good visualization for common use cases such as technial plans, design explorations and more out of the box.
+- **Battery included** - Lavish Editor teaches your agent good visualization for common use cases such as product or technical plans, design explorations and more out of the box.
 
 Lavish Editor is an [AXI](https://axi.md), which means -
 
@@ -48,7 +48,7 @@ Lavish Editor is an [AXI](https://axi.md), which means -
 Just tell your agent:
 
 ```sh
-Use `npx lavish-axi` to write a technical plan for what we discussed.
+Use `npx lavish-axi` to write a product or technical plan for what we discussed.
 ```
 
 ## Install
@@ -101,6 +101,8 @@ pnpm link
 - **Feedback controls** - Mark buttons, choices, and other interactive elements with `data-lavish-action` so Lavish does not annotate them, then call `window.lavish.queuePrompt()` or `window.lavish.sendQueuedPrompts()` from the control handler.
 - **Agent presence** - The browser shows when no agent is listening, keeps queued feedback for the next successful `lavish-axi poll` send even across reloads, and only blocks sending while the agent is working on delivered feedback.
 - **Precise targets** - Text annotations include selected text plus range anchors, so agents are not limited to whole-element selectors.
+- **Server cleanup** - The detached server stops after the last session ends when nothing is connected, or after `LAVISH_AXI_IDLE_TIMEOUT_MS` (default 30 minutes) with no browser or poll connections.
+  Set `LAVISH_AXI_IDLE_TIMEOUT_MS=0` or `off` to disable idle self-shutdown.
 - **Local-first state** - Session state stays under `.lavish-axi/` in the workspace.
 
 ## CLI Reference
@@ -111,6 +113,7 @@ pnpm link
 | `lavish-axi <html-file>`      | Open or resume a Lavish Editor session.                                                                                  |
 | `lavish-axi poll <html-file>` | Long-poll until the user sends feedback or ends the session.                                                             |
 | `lavish-axi end <html-file>`  | End a session.                                                                                                           |
+| `lavish-axi stop`             | Shut down the background server.                                                                                         |
 | `lavish-axi playbook [id]`    | List focused artifact guidance or show one playbook.                                                                     |
 | `lavish-axi design`           | Show CDN snippet + DaisyUI component reference (opt-in).                                                                 |
 | `lavish-axi setup hooks`      | Install or repair optional SessionStart hooks for Claude Code, Codex, and OpenCode; restart the agent session afterward. |
@@ -125,6 +128,7 @@ Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `diff`, `input`, `
 | `lavish-axi <html-file>` | `--no-open`           | Ensure the server/session exists without opening another browser window.                                                                                                                                                            |
 | `lavish-axi poll`        | `--agent-reply "..."` | Show the agent's reply in the existing browser chat before polling again.                                                                                                                                                           |
 | `lavish-axi poll`        | `--timeout-ms <ms>`   | Test/debug escape hatch only; agents should normally omit it.                                                                                                                                                                       |
+| `lavish-axi stop`        | `--port <port>`       | Shut down a server running on a non-default port.                                                                                                                                                                                   |
 | `lavish-axi server`      | `--verbose`           | Log session and watcher events to stderr; can also be enabled with `LAVISH_AXI_DEBUG=1`. Detached server output is appended to `~/.lavish-axi/server.log` (or `LAVISH_AXI_STATE_DIR/server.log`) for startup and crash diagnostics. |
 
 ## Development

package/dist/cli.mjs

@@ -577,31 +577,28 @@ var PLAYBOOKS = [
   },
   {
     id: "plan",
-    use_when: "Explain a technical plan before implementation",
+    use_when: "Explain a product or technical plan before implementation",
     choose: [
       "Use this when the user needs to inspect a feature approach before implementation begins.",
-      "Use it when state, APIs, files, tests, or edge cases are numerous enough to deserve a visual map.",
-      "Use a lighter comparison or diagram playbook when the plan is only a small design choice."
+      "Use it when the user explicitly asked for a PRD, technical design, implementation plan or proposal.",
+      "Use a lighter comparison or diagram playbook when the plan is only a single small design choice."
     ],
     structure: [
-      "Start with the problem, the desired behavior, and what is out of scope.",
-      "Show affected state, commands, functions, files, and user-visible behavior.",
-      "Include edge cases and tests before implementation notes so risk is visible early."
+      "Start with the goal, the current state, and desired behavior.",
+      "Then describe a proposed approach, focusing on high level decisions.",
+      "At the end, list any risks you see, and open questions you have, and follow the 'comparison' playbook to provide options for the user to choose from."
     ],
     design_rules: [
       "Verify each claim against the codebase before presenting it as fact.",
-      "Keep code snippets focused on the pattern or seam, not full-file dumps.",
-      "Make test requirements concrete enough to drive TDD."
+      "When discussing frontend experiences, prefer visually mocking the experience under a consistent design system as the real product over describing it with text.",
+      "The plan needs to be self-contained enough that another developer can read it and fully implement the proposal."
     ],
     pitfalls: [
-      "Do not invent extension points or APIs that are not present in the repo.",
-      "Do not turn a plan into a long prose essay when state and file maps would be clearer.",
+      "Do not leave resolved open questions in the artifact. Update existing content to reflect the decision and remove the open question.",
+      "Do not only focus on ambiguous decisions and omit the actual proposal.",
       "Do not omit failure modes, migration concerns, or backwards compatibility questions."
     ],
-    lavish_notes: [
-      "A Lavish plan should make uncertainties easy to annotate before code exists.",
-      "Use controls for scope choices so the user can queue a precise implementation direction."
-    ]
+    lavish_notes: ["A Lavish plan should make a plan and its uncertainties easy to annotate before code exists."]
   },
   {
     id: "diff",
@@ -1198,7 +1195,24 @@ var designAssetUrls = {
     type: "application/javascript"
   }
 };
-async function serve({ port, stateFile: stateFile2, version = "", debug = false, log = null, pollHeartbeatMs = 15e3 }) {
+var DEFAULT_IDLE_TIMEOUT_MS = 30 * 6e4;
+function resolveIdleTimeoutMs(env = process.env) {
+  const raw = env.LAVISH_AXI_IDLE_TIMEOUT_MS?.trim();
+  if (raw === void 0 || raw === "") return DEFAULT_IDLE_TIMEOUT_MS;
+  if (raw === "0" || raw.toLowerCase() === "off") return null;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) return DEFAULT_IDLE_TIMEOUT_MS;
+  return value;
+}
+async function serve({
+  port,
+  stateFile: stateFile2,
+  version = "",
+  debug = false,
+  log = null,
+  pollHeartbeatMs = 15e3,
+  idleTimeoutMs = resolveIdleTimeoutMs()
+}) {
   const app = express();
   const store = new SessionStore(stateFile2);
   const events = new EventEmitter();
@@ -1270,6 +1284,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
         heartbeat.unref?.();
       }
       setPollActive(key, activePolls, deliveredFeedback, events, true);
+      refreshIdleTimer();
       const timer = timeoutMs === null ? null : setTimeout(() => respond().catch(handleRespondError), timeoutMs);
       let cleaned = false;
       let responding = false;
@@ -1281,6 +1296,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
         events.off("feedback", onFeedback);
         events.off("ended", onFeedback);
         setPollActive(key, activePolls, deliveredFeedback, events, false);
+        refreshIdleTimer();
       };
       const respond = async () => {
         if (responding || res.writableEnded) return;
@@ -1329,6 +1345,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
       clearFeedbackDelivery(req.params.key, activePolls, deliveredFeedback, events);
       events.emit("ended", req.params.key);
       res.json({ status: "ended" });
+      await shutdownIfNoLiveSessions();
     } catch (error) {
       next(error);
     }
@@ -1355,6 +1372,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
       clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
       events.emit("ended", key);
       res.json({ status: "ended" });
+      await shutdownIfNoLiveSessions();
     } catch (error) {
       next(error);
     }
@@ -1417,6 +1435,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
         connection: "keep-alive"
       });
       sseClients.add(res);
+      refreshIdleTimer();
       const session = await store.findByKey(req.params.key);
       const sendReload = (key) => {
         if (key === req.params.key) {
@@ -1457,6 +1476,7 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
         events.off("reload", sendReload);
         events.off("agent-reply", sendAgentReply);
         events.off("agent-presence", sendPresence);
+        refreshIdleTimer();
       });
     } catch (error) {
       next(error);
@@ -1502,6 +1522,10 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
   function shutdown() {
     if (shuttingDown) return;
     shuttingDown = true;
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
     for (const res of sseClients) {
       try {
         res.write("event: chrome-reload\ndata: {}\n\n");
@@ -1520,6 +1544,35 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
       httpServer.closeAllConnections();
     }
   }
+  let idleTimer = null;
+  function refreshIdleTimer() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+    if (shuttingDown || idleTimeoutMs == null) return;
+    if (sseClients.size > 0 || activePolls.size > 0) return;
+    idleTimer = setTimeout(() => {
+      idleTimer = null;
+      if (!shuttingDown && sseClients.size === 0 && activePolls.size === 0) {
+        logEvent?.(`idle for ${idleTimeoutMs}ms with no connections, shutting down`);
+        shutdown();
+      }
+    }, idleTimeoutMs);
+    idleTimer.unref?.();
+  }
+  async function shutdownIfNoLiveSessions() {
+    if (sseClients.size > 0 || activePolls.size > 0) return;
+    try {
+      const sessions = await store.listSessions();
+      if (sessions.every((session) => session.status === "ended")) {
+        logEvent?.("last open session ended with no live connections, shutting down");
+        setImmediate(shutdown);
+      }
+    } catch {
+    }
+  }
+  refreshIdleTimer();
   return {
     port: httpServer.address().port,
     close: async () => {
@@ -1835,9 +1888,9 @@ function normalizePagePath(path5) {
 }
 
 // src/cli.js
-var COMMANDS = /* @__PURE__ */ new Set(["open", "poll", "end", "server", "playbook", "design", "setup"]);
+var COMMANDS = /* @__PURE__ */ new Set(["open", "poll", "end", "stop", "server", "playbook", "design", "setup"]);
 var DESCRIPTION = "Lavish Editor helps agents turn rich HTML artifacts into collaborative human review surfaces. Whenever you are about to give user a complex response that will be easier to understand via a rich / interactive page, consider using Lavish Editor. First generate an interactive HTML artifact according to user request, then run `lavish-axi <html-file>` so the user can visually review it, annotate elements or selected text, queue prompts, and send feedback back through `lavish-axi poll`.";
-var VERSION = "0.1.16";
+var VERSION = "0.1.18";
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
@@ -1865,6 +1918,7 @@ async function run(argv) {
         open: openCommand,
         poll: pollCommand,
         end: endCommand,
+        stop: stopCommand,
         playbook: playbookCommand,
         design: designCommand,
         setup: setupCommand,
@@ -1930,9 +1984,10 @@ function createHomeOutput({ bin, sessions, includeSessions = true }) {
       "Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work",
       "Run `lavish-axi poll <html-file>` to wait for user feedback",
       "Run `lavish-axi end <html-file>` to end a session",
+      "Run `lavish-axi stop` to shut down the background server (it also self-stops when idle or after the last session ends with nothing connected)",
       "Run `lavish-axi playbook <playbook_id>` for focused artifact guidance",
       DESIGN_SYSTEM_HINT,
-      "Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, technical plan, comparison, report, or browser-based feedback loop"
+      "Use lavish-axi when the user asks for a visual artifact, HTML explainer, interactive prototype, review surface, product or technical plan, comparison, report, or browser-based feedback loop"
     ]
   };
 }
@@ -2031,6 +2086,35 @@ async function endCommand(args) {
   const response = await postJson(`${baseUrl}/api/end`, { file: absolute });
   return { session: { file: absolute, status: response.status || "ended" } };
 }
+async function stopCommand(args) {
+  const port = Number(flagValue(args, "--port") || defaultPort());
+  const baseUrl = `http://${LOOPBACK_HOST}:${port}`;
+  return shutdownServerOnPort(port, { baseUrl, currentVersion: VERSION });
+}
+async function shutdownServerOnPort(port, {
+  baseUrl = `http://${LOOPBACK_HOST}:${port}`,
+  currentVersion = VERSION,
+  fetchHealth: healthFetcher = fetchHealth,
+  requestShutdown: shutdownRequester = requestShutdown,
+  waitForPortFree: portFreeWaiter = waitForPortFree,
+  killProcessOnPort: portKiller = killProcessOnPort,
+  processMatchesLavish = processOnPortMatchesLavish
+} = {}) {
+  const health = await healthFetcher(baseUrl);
+  if (!health) {
+    return { server: { status: "not-running", port } };
+  }
+  if (!await canControlServerOnPort(port, health, processMatchesLavish)) {
+    return { server: { status: "not-lavish", port } };
+  }
+  await shutdownRequester(baseUrl);
+  let freed = await portFreeWaiter(baseUrl, 3e3);
+  if (!freed && shouldKillProcessOnPort(currentVersion, health)) {
+    portKiller(port);
+    freed = await portFreeWaiter(baseUrl, 3e3);
+  }
+  return { server: { status: freed ? "stopped" : "stopping", port } };
+}
 async function playbookCommand(args) {
   return createPlaybookOutput(args);
 }
@@ -2094,6 +2178,11 @@ async function ensureServer({ forceRestart = false } = {}) {
     return baseUrl;
   }
   if (existing) {
+    if (!await canControlServerOnPort(port, existing, processOnPortMatchesLavish)) {
+      throw new AxiError(`Port ${port} is occupied by a non-Lavish server`, "SERVER_ERROR", [
+        `Stop the process using port ${port}, or set LAVISH_AXI_PORT to another port`
+      ]);
+    }
     await requestShutdown(baseUrl);
     const freed = await waitForPortFree(baseUrl, 2e3);
     if (!freed) {
@@ -2135,6 +2224,12 @@ function shouldKillProcessOnPort(currentVersion, healthBody) {
   if (healthBody.app !== "lavish-axi") return false;
   return healthBody.version !== currentVersion;
 }
+async function canControlServerOnPort(port, healthBody, processMatchesLavish) {
+  if (!healthBody || typeof healthBody !== "object") return false;
+  if (healthBody.app === "lavish-axi") return true;
+  if (typeof healthBody.version === "string" && healthBody.version !== "") return false;
+  return processMatchesLavish(port);
+}
 async function fetchHealth(baseUrl) {
   try {
     const response = await fetch(`${baseUrl}/health`);
@@ -2174,6 +2269,23 @@ function killProcessOnPort(port) {
   } catch {
   }
 }
+function processOnPortMatchesLavish(port) {
+  try {
+    const pids = spawnSync("lsof", ["-t", `-iTCP:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
+    if (pids.status !== 0) return false;
+    for (const line of pids.stdout.split("\n")) {
+      const pid = Number(line.trim());
+      if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) continue;
+      const command = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+      if (command.status === 0 && /lavish-axi/.test(command.stdout)) {
+        return true;
+      }
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
 async function startServer(port) {
   await ensureStateDir();
   const entry = resolveServerEntry();
@@ -2275,6 +2387,7 @@ Usage:
   lavish-axi <html-file>
   lavish-axi poll <html-file> [--agent-reply "..."]
   lavish-axi end <html-file>
+  lavish-axi stop
   lavish-axi playbook [playbook_id]
   lavish-axi design
   lavish-axi setup hooks
@@ -2296,6 +2409,10 @@ This command long-polls indefinitely for queued user prompts, then returns them
   end: `Usage: lavish-axi end <html-file>
 
 End a Lavish Editor session.
+`,
+  stop: `Usage: lavish-axi stop [--port <port>]
+
+Shut down the background Lavish Editor server. The server also stops itself when no browser or poll has been connected for a while (LAVISH_AXI_IDLE_TIMEOUT_MS, default 30m) and immediately when the last session ends with nothing connected.
 `,
   playbook: `Usage: lavish-axi playbook [playbook_id]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavish-axi",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "packageManager": "pnpm@11.1.1",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "type": "module",