lavish-axi 0.1.27 → 0.1.29

package/README.md

@@ -53,6 +53,7 @@ npx skills add kunchenguid/lavish-axi --skill lavish
 
 That is the entire setup - no npm install needed.
 The skill teaches your agent to run Lavish through `npx -y lavish-axi`, so the CLI comes along on demand.
+Its frontmatter also includes Hermes Agent metadata, so Hermes-compatible harnesses can categorize and surface it as a first-class productivity skill.
 
 Then, in agents that expose skills as slash commands (Claude Code, for example), invoke it directly:
 
@@ -60,7 +61,7 @@ Then, in agents that expose skills as slash commands (Claude Code, for example),
 /lavish let's discuss our plan here
 ```
 
-Or just ask for anything that is easier to grasp visually - a plan, comparison, diagram, table, diff, or report - and the agent loads the skill on its own when it recognizes the task.
+Or just ask for anything that is easier to grasp visually - a plan, comparison, diagram, table, code view, or report - and the agent loads the skill on its own when it recognizes the task.
 
 By default the skill lands in the current project's skills directory (`.claude/skills/`, for example); add `-g` to install it for all projects (`~/.claude/skills/`).
 
@@ -143,6 +144,7 @@ pnpm link
 - **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.
+- **Network binding** - The server binds to loopback (`127.0.0.1`) by default. Set `LAVISH_AXI_HOST` to bind elsewhere; a wildcard (`0.0.0.0` or `::`) binds every interface. Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. Set `LAVISH_AXI_LINK_HOST` to control the hostname written into generated session links (defaults to the bind address, or loopback when bound to a wildcard).
 
 ## CLI Reference
 
@@ -158,7 +160,7 @@ pnpm link
 | `lavish-axi setup hooks`      | Install or repair optional SessionStart hooks for Claude Code, Codex, and OpenCode; restart the agent session afterward.    |
 | `lavish-axi server`           | Run the local Lavish Editor server.                                                                                         |
 
-Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `diff`, `input`, `slides`.
+Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `code`, `input`, `slides`.
 One artifact often combines several playbooks, such as a plan that includes a comparison and a diagram, so read every playbook relevant to the artifact for the best quality.
 
 ### Flags

package/dist/cli.mjs

@@ -474,6 +474,25 @@ import { mkdir } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 var LOOPBACK_HOST = "127.0.0.1";
+var IPV6_LOOPBACK_HOST = "::1";
+var WILDCARD_BIND_LOOPBACK = /* @__PURE__ */ new Map([
+  ["0.0.0.0", LOOPBACK_HOST],
+  ["::", IPV6_LOOPBACK_HOST]
+]);
+function bindHost(env = process.env) {
+  return env.LAVISH_AXI_HOST?.trim() || LOOPBACK_HOST;
+}
+function clientHost(env = process.env) {
+  const host = bindHost(env);
+  return WILDCARD_BIND_LOOPBACK.get(host) ?? host;
+}
+function linkHost(env = process.env) {
+  return env.LAVISH_AXI_LINK_HOST?.trim() || clientHost(env);
+}
+function hostForUrl(host) {
+  if (host.includes(":") && !host.startsWith("[")) return `[${host}]`;
+  return host;
+}
 function stateDir() {
   return process.env.LAVISH_AXI_STATE_DIR || path.join(os.homedir(), ".lavish-axi");
 }
@@ -602,31 +621,64 @@ var PLAYBOOKS = [
     lavish_notes: ["A Lavish plan should make a plan and its uncertainties easy to annotate before code exists."]
   },
   {
-    id: "diff",
-    use_when: "Present code or PR changes with evidence and findings",
+    id: "code",
+    use_when: "Render source code, code files, patches, PR diffs, and before/after code inside Lavish artifacts",
     choose: [
-      "Use this when the artifact is meant to help a human inspect a diff, PR, or local change set.",
-      "Use findings as the primary shape when bugs or regressions are possible.",
-      "Use architecture and file maps when the change is broad enough that text diffs lose the thread."
+      "Use this whenever an artifact shows source code: a snippet, full file, patch, PR diff, local change set, or before/after code.",
+      "Use File for one code file, FileDiff for old/new versions or parsed patch metadata, and CodeView only when several files or diffs need coordinated navigation.",
+      "Choose split layout for careful side-by-side review when width allows; choose unified layout when space is tight, changes are mostly additive, or mobile readability matters."
     ],
     structure: [
-      "Start with the review scope and the most important findings.",
-      "Show changed areas, tests, docs implications, and any behavioral deltas.",
-      "Keep evidence close to each claim with file paths, line references, or command outputs."
+      "Place the path, language, and reason to inspect the code immediately before each rendered file or diff.",
+      "Keep evidence close to each claim with file paths, line references, or annotations next to the relevant code.",
+      "For multi-file changes, group files by user-facing area or task instead of dumping a raw patch in repository order."
     ],
     design_rules: [
-      "Order findings by severity before summaries or praise.",
-      "Separate observed facts from inferred rationale.",
-      "Use severity, confidence, and affected file references consistently."
+      `Rendering MUST use @pierre/diffs, not hand-rolled <pre> blocks or another diff library. This verified no-build standalone HTML snippet renders one file and one split diff from esm.sh:
+\`\`\`html
+<div id="file"></div>
+<div id="diff"></div>
+<script type="module">
+  import { File, FileDiff } from "https://esm.sh/@pierre/diffs@1.2.10?bundle";
+
+  const theme = { light: "github-light", dark: "github-dark" };
+  const options = { theme, themeType: "dark", overflow: "wrap" };
+  const oldFile = {
+    name: "src/greeting.ts",
+    contents: "export function greet(name: string) {\\n  return \\"Hello \\" + name;\\n}\\n\\nconsole.log(greet(\\"Lavish\\"));\\n",
+  };
+  const newFile = {
+    name: "src/greeting.ts",
+    contents: "export function greet(name: string) {\\n  return \\"Hello, \\" + name + \\"!\\";\\n}\\n\\nconsole.log(greet(\\"Lavish\\"));\\n",
+  };
+
+  new File(options).render({
+    containerWrapper: document.querySelector("#file"),
+    file: newFile,
+  });
+
+  new FileDiff({ ...options, diffStyle: "split" }).render({
+    containerWrapper: document.querySelector("#diff"),
+    oldFile,
+    newFile,
+  });
+
+</script>
+\`\`\``,
+      "Pick a Shiki theme pair that matches the artifact's DaisyUI or Tailwind direction and light or dark mode; replace the GitHub pair above when the page is not GitHub-like.",
+      'Use FileDiff diffStyle: "split" for side-by-side review and diffStyle: "unified" for stacked reading; keep overflow: "wrap" unless horizontal alignment is essential.',
+      "Use @pierre/diffs line annotations, selections, and headers when calling out specific lines so notes stay attached to code."
     ],
     pitfalls: [
-      "Do not make a review artifact that is only a pretty changelog.",
-      "Do not state decision rationale as fact when it was inferred from code shape.",
-      "Do not skip tests and docs impact when public behavior changes."
+      "Do not render code as static screenshots, plain <pre> blocks, or markdown pasted into HTML.",
+      "Do not choose an arbitrary default Shiki theme that clashes with the page palette or dark mode.",
+      "Do not show huge unrelated files when a focused render range, parsed patch file, or grouped summary would be clearer.",
+      "Do not separate a claim from the code lines that prove it."
     ],
     lavish_notes: [
-      "A Lavish review should let the user click a finding and ask for the exact fix or clarification.",
-      "If no issue is found in a category, say so explicitly rather than leaving ambiguity."
+      "A Lavish code artifact should make each file, hunk, and relevant line easy to annotate precisely.",
+      "When a user action should trigger a fix, queue prompts that name the file path, line range, and desired change.",
+      "If the artifact combines code with a plan, table, or comparison, read those playbooks too and keep @pierre/diffs responsible for the code surface."
     ]
   },
   {
@@ -1229,7 +1281,9 @@ async function serve({
   debug = false,
   log = null,
   pollHeartbeatMs = 15e3,
-  idleTimeoutMs = resolveIdleTimeoutMs()
+  idleTimeoutMs = resolveIdleTimeoutMs(),
+  host = bindHost(),
+  linkHost: linkHostName = linkHost()
 }) {
   const app = express();
   const store = new SessionStore(stateFile2);
@@ -1259,7 +1313,7 @@ async function serve({
     try {
       const file = await canonicalFile(req.body.file);
       const key = sessionKey(file);
-      const url = `http://${LOOPBACK_HOST}:${publicPort}/session/${key}`;
+      const url = `http://${hostForUrl(linkHostName)}:${publicPort}/session/${key}`;
       const existing = await store.findByKey(key);
       const session = await store.upsertSession(file, url);
       if (existing?.status === "ended") {
@@ -1532,8 +1586,11 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
   app.use((error, req, res, _next) => {
     res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
   });
-  const httpServer = await new Promise((resolve) => {
-    const s = app.listen(port, LOOPBACK_HOST, () => resolve(s));
+  const httpServer = await new Promise((resolve, reject) => {
+    const s = app.listen(port, host, () => {
+      if (s.address()) resolve(s);
+    });
+    s.once("error", reject);
   });
   publicPort = httpServer.address().port;
   let shuttingDown = false;
@@ -1947,7 +2004,7 @@ function normalizePagePath(path5) {
 // src/cli.js
 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.27";
+var VERSION = "0.1.29";
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
@@ -2195,11 +2252,11 @@ async function endCommand(args) {
 }
 async function stopCommand(args) {
   const port = Number(flagValue(args, "--port") || defaultPort());
-  const baseUrl = `http://${LOOPBACK_HOST}:${port}`;
+  const baseUrl = `http://${hostForUrl(clientHost())}:${port}`;
   return shutdownServerOnPort(port, { baseUrl, currentVersion: VERSION });
 }
 async function shutdownServerOnPort(port, {
-  baseUrl = `http://${LOOPBACK_HOST}:${port}`,
+  baseUrl = `http://${hostForUrl(clientHost())}:${port}`,
   currentVersion = VERSION,
   fetchHealth: healthFetcher = fetchHealth,
   requestShutdown: shutdownRequester = requestShutdown,
@@ -2279,7 +2336,7 @@ function isHtmlPath(file) {
 }
 async function ensureServer({ forceRestart = false } = {}) {
   const port = defaultPort();
-  const baseUrl = `http://${LOOPBACK_HOST}:${port}`;
+  const baseUrl = `http://${hostForUrl(clientHost())}:${port}`;
   const existing = await fetchHealth(baseUrl);
   if (existing && !shouldRestartServer(VERSION, existing, forceRestart)) {
     return baseUrl;
@@ -2523,7 +2580,7 @@ Shut down the background Lavish Editor server. The server also stops itself when
 `,
   playbook: `Usage: lavish-axi playbook [playbook_id]
 
-List focused artifact guidance playbooks, or show one playbook by ID. Known IDs: diagram, table, comparison, plan, diff, input, slides.
+List focused artifact guidance playbooks, or show one playbook by ID. Known IDs: diagram, table, comparison, plan, code, input, slides.
 
 One artifact often combines several playbooks (for example a plan that includes a comparison and a diagram), so read every playbook relevant to the artifact, not just one, for the best quality.
 
@@ -2543,6 +2600,8 @@ Install or repair agent SessionStart hooks for lavish-axi ambient context in Cla
   server: `Usage: lavish-axi server [--port 4387] [--verbose]
 
 Run the local Lavish Editor server. Pass --verbose (or set LAVISH_AXI_DEBUG=1) to log session and watcher events to stderr. Detached server output is appended to ~/.lavish-axi/server.log, or LAVISH_AXI_STATE_DIR/server.log when set, for startup and crash diagnostics.
+
+LAVISH_AXI_HOST sets the bind address (default 127.0.0.1; a wildcard 0.0.0.0 or :: binds every interface). Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. LAVISH_AXI_LINK_HOST sets the hostname written into generated session links (default: the bind address, or loopback when bound to a wildcard). LAVISH_AXI_NO_OPEN=1 (or --no-open) suppresses the local browser launch.
 `
 };
 

package/package.json

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

package/skills/lavish/SKILL.md

@@ -2,6 +2,11 @@
 name: lavish
 description: Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.
 argument-hint: <what the artifact should show>
+author: Kun Chen (kunchenguid)
+metadata:
+  hermes:
+    tags: [html, review, artifacts, visualization]
+    category: productivity
 ---
 
 # Lavish Editor
@@ -48,7 +53,7 @@ One artifact often combines several playbooks (for example a plan that includes
 - `table` - Turn dense records into scan-friendly review surfaces
 - `comparison` - Show options, tradeoffs, and current vs target behavior
 - `plan` - Explain a product or technical plan before implementation
-- `diff` - Present code or PR changes with evidence and findings
+- `code` - Render source code, code files, patches, PR diffs, and before/after code inside Lavish artifacts
 - `input` - Must be used when the agent needs to collect user input on decisions, choices, preferences, triage, scope, or other structured feedback from within the artifact
 - `slides` - Create a deliberate presentation when slides are requested