@ammduncan/easel 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.6.2 — 2026-06-04
+
+### Fixed
+- **`setup` now actually puts `easel` on PATH, making the documented bare CLI commands truthful.** The README's CLI section documents `easel open / update / restart / …`, but neither install path ever exposed the binary: `npx -y @ammduncan/easel setup` runs once from the ephemeral npx cache and leaves nothing behind, and clone installs' `bin/easel setup` never linked. Setup now closes the gap per install flavor: clone installs get `npm link` (skipped when `easel` already resolves); npx-cache runs get a real `npm install -g` pinned to their own version, then **delegate setup to the global copy** so the MCP/hook registrations point at paths that survive npx cache pruning (the cache-pruning drift left one machine's MCP pinned to a stale 0.5.1 cache while 0.6.x shipped). Failures degrade to a printed hint — setup never hard-fails on the PATH step.
+- **`easel update` now works for npm installs.** It previously assumed a git checkout (`git pull` flavor, "clone installs only") and just failed elsewhere. Without a `.git` dir it now runs `npm install -g @ammduncan/easel@latest` and re-runs setup from the new copy.
+
 ## 0.6.1 — 2026-06-04
 
 ### Changed

package/README.md

@@ -31,7 +31,7 @@ Requires Node 20+.
 npx -y @ammduncan/easel setup
 ```
 
-That registers the MCP at user scope, installs the `using-easel` skill so the agent knows when to push, and adds the `SessionStart` hooks that resolve session IDs and auto-open the tab. Restart Claude Code and you're done.
+That registers the MCP at user scope, installs the `using-easel` skill so the agent knows when to push, adds the `SessionStart` hooks that resolve session IDs and auto-open the tab, and installs the package globally so the bare `easel` command works from any shell. Restart Claude Code and you're done.
 
 ### Cursor / Claude Desktop / Windsurf / Codex
 
@@ -81,6 +81,8 @@ npm install && npm run build
 bin/easel setup
 ```
 
+Setup runs `npm link`, so bare `easel` works from any shell afterwards.
+
 ## Tools the agent gets
 
 | Tool | What it does |
@@ -134,7 +136,7 @@ easel config                   print / set { preset, theme, density }
 easel setup                    Claude Code: hooks + MCP + skill
 easel setup --client <name>    register the MCP in another client (cursor, claude-desktop, windsurf, codex)
 easel restart                  kill + respawn the HTTP server (handy after a build)
-easel update                   git pull + build + setup (clone installs only)
+easel update                   clone installs: git pull + build + setup · npm installs: npm install -g @latest + setup
 easel server                   run the HTTP server in the foreground (debug)
 easel version
 ```

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from "node:child_process";
 import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { ensureHttpServer, readLock } from "./server-manager.js";
@@ -11,6 +11,7 @@ import { registerSession } from "./session-store.js";
 import { listClients, setupClient, } from "./client-setup.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = resolve(__dirname, "..");
+const NPM_PKG = "@ammduncan/easel";
 function help() {
     console.log(`easel — live browser feed for Claude Code for Claude Code sessions
 
@@ -28,7 +29,7 @@ Usage:
   easel setup --client claude-desktop      register MCP in ~/Library/Application Support/Claude/claude_desktop_config.json
   easel setup --client windsurf            register MCP in ~/.codeium/windsurf/mcp_config.json
   easel setup --client codex               register MCP in ~/.codex/config.toml + copy skill to ~/.codex/skills/
-  easel update          git pull + npm install + build + setup (re-runs setup to apply new conventions)
+  easel update          clone installs: git pull + build + setup · npm installs: npm install -g @latest + setup
   easel mcp             run the stdio MCP server in the foreground (used by clients)
   easel restart         kill the running HTTP server and respawn it (picks up new builds/paths)
   easel server          run the HTTP server in the foreground (debug)
@@ -97,7 +98,91 @@ function openInBrowser(url) {
         console.error(`[easel] couldn't open browser: ${err.message}`);
     }
 }
+function binResolvesOnPath() {
+    const cmd = process.platform === "win32" ? "where" : "which";
+    try {
+        const r = spawnSync(cmd, ["easel"], { encoding: "utf-8" });
+        return r.status === 0 && r.stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function pkgVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(PROJECT_ROOT, "package.json"), "utf-8"));
+        return pkg.version ?? "latest";
+    }
+    catch {
+        return "latest";
+    }
+}
+function globalPkgDir() {
+    try {
+        const r = spawnSync("npm", ["root", "-g"], { encoding: "utf-8" });
+        if (r.status !== 0)
+            return null;
+        const dir = join(r.stdout.trim(), NPM_PKG);
+        return existsSync(dir) ? dir : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Re-runs setup from the globally installed copy so its registrations point at
+// the global paths. Returns false if there is no global copy to delegate to.
+function rerunSetupFromGlobal() {
+    const dir = globalPkgDir();
+    if (!dir) {
+        return false;
+    }
+    const r = spawnSync("node", [join(dir, "dist", "cli.js"), "setup"], {
+        stdio: "inherit",
+        env: { ...process.env, EASEL_SETUP_CHILD: "1" },
+    });
+    return r.status === 0;
+}
+// Make bare `easel` work after setup, as the README documents. Clone installs
+// get `npm link`. npx-cache installs get a real global install — the cache is
+// pruned unpredictably — and setup is then re-run from the global copy so the
+// MCP/hook registrations point at paths that survive pruning.
+// Returns true when setup was fully delegated to the global copy.
+function ensureBinOnPath() {
+    const inNpxCache = PROJECT_ROOT.split(sep).includes("_npx");
+    if (!inNpxCache) {
+        if (binResolvesOnPath()) {
+            return false;
+        }
+        const r = spawnSync("npm", ["link", "--silent", "--no-audit", "--no-fund"], {
+            cwd: PROJECT_ROOT,
+            stdio: "ignore",
+        });
+        if (r.status === 0) {
+            console.log("  - linked `easel` into the global bin (npm link)");
+        }
+        else {
+            console.warn(`  - couldn't put \`easel\` on PATH — run \`npm link\` in ${PROJECT_ROOT}`);
+        }
+        return false;
+    }
+    const version = pkgVersion();
+    console.log(`[easel] installing ${NPM_PKG}@${version} globally so \`easel\` is on PATH…`);
+    const installed = spawnSync("npm", ["install", "-g", "--silent", "--no-audit", "--no-fund", `${NPM_PKG}@${version}`], { stdio: "inherit" });
+    if (installed.status !== 0 || !rerunSetupFromGlobal()) {
+        console.warn(`  - global install failed — \`easel\` won't be on PATH; run \`npm install -g ${NPM_PKG}\` manually`);
+        return false;
+    }
+    return true;
+}
 function cmdSetup() {
+    // Put `easel` on PATH first — for npx-cache runs this delegates the whole
+    // setup to a freshly installed global copy (so registered paths outlive the
+    // cache), in which case there's nothing left to do here.
+    if (!process.env.EASEL_SETUP_CHILD) {
+        if (ensureBinOnPath()) {
+            return;
+        }
+    }
     mkdirSync(HOOK_DIR, { recursive: true });
     const settingsPath = join(homedir(), ".claude", "settings.json");
     const hookScript = resolve(PROJECT_ROOT, "scripts", "easel-session-id.mjs");
@@ -264,6 +349,25 @@ async function cmdConfig(args) {
 function cmdUpdate() {
     console.log("[easel] checking for updates…");
     const run = (cmd, args) => spawnSync(cmd, args, { stdio: "inherit", cwd: PROJECT_ROOT });
+    // npm/global installs have no git checkout — update from the registry and
+    // re-run setup from the new copy so registrations track the new paths.
+    if (!existsSync(join(PROJECT_ROOT, ".git"))) {
+        const installed = run("npm", [
+            "install",
+            "-g",
+            "--no-audit",
+            "--no-fund",
+            `${NPM_PKG}@latest`,
+        ]);
+        if (installed.status !== 0) {
+            console.error("[easel] npm install -g failed");
+            process.exitCode = 1;
+            return;
+        }
+        rerunSetupFromGlobal();
+        console.log("[easel] updated. Restart Claude Code to pick up tool/skill changes.");
+        return;
+    }
     let r = run("git", ["fetch", "--quiet", "origin", "main"]);
     if (r.status !== 0) {
         console.error("[easel] git fetch failed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "A live browser tab for every Claude Code (and MCP) session. The push MCP tool appends HTML cards to a scrolling feed you keep open in split-screen.",
   "type": "module",
   "license": "MIT",