@ammduncan/easel 0.2.0

package/dist/session-id.js

@@ -0,0 +1,78 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { HOOK_DIR } from "./paths.js";
+/**
+ * Resolves the session id that owns this MCP process. Tries, in order:
+ *   1. EASEL_SESSION_ID env var (explicit override for any client)
+ *   2. CLAUDE_CODE_SESSION_ID / CLAUDE_SESSION_ID (Claude Code)
+ *   3. Hook file at ~/.easel/hook/cc-session-<ppid>.txt (Claude Code's
+ *      SessionStart hook writes this; pitstop-style PPID bridging)
+ *   4. Most-recently-modified transcript under ~/.claude/projects/<cwd>/
+ *      (Claude Code transcript scan)
+ *   5. Synthetic id derived from this MCP child's PPID — gives every other
+ *      MCP client (Cursor, Windsurf, Claude Desktop, etc.) a stable session
+ *      per chat without requiring any hook. The MCP child IS the session.
+ *
+ * Always returns a value from tier 5 if all higher tiers miss, so non-CC
+ * clients are usable out of the box.
+ */
+export function resolveClaudeSessionId(opts = {}) {
+    const home = opts.homeDir ?? homedir();
+    const cwd = opts.cwd ?? process.cwd();
+    const ppid = opts.ppid ?? process.ppid;
+    const env = opts.env ?? process.env;
+    const explicit = env.EASEL_SESSION_ID;
+    if (explicit)
+        return explicit;
+    const fromCcEnv = env.CLAUDE_CODE_SESSION_ID ?? env.CLAUDE_SESSION_ID;
+    if (fromCcEnv)
+        return fromCcEnv;
+    const hookFile = join(HOOK_DIR, `cc-session-${ppid}.txt`);
+    try {
+        const id = readFileSync(hookFile, "utf-8").trim();
+        if (id)
+            return id;
+    }
+    catch {
+        /* fall through */
+    }
+    try {
+        const encoded = cwd.replace(/\//g, "-");
+        const dir = join(home, ".claude", "projects", encoded);
+        let bestId;
+        let bestMtime = 0;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            const m = statSync(join(dir, f)).mtimeMs;
+            if (m > bestMtime) {
+                bestMtime = m;
+                bestId = f.slice(0, -".jsonl".length);
+            }
+        }
+        if (bestId)
+            return bestId;
+    }
+    catch {
+        /* fall through */
+    }
+    return syntheticSessionIdFromPpid(ppid);
+}
+/**
+ * Mints a stable, UUID-shaped id from the parent PID and parent boot time.
+ * Same PPID across an MCP-child restart → same id (so a flaky child doesn't
+ * spawn a new tab); different chat / different client process → different id.
+ */
+function syntheticSessionIdFromPpid(ppid) {
+    const seed = `mcp-ppid-${ppid}`;
+    const hex = createHash("sha1").update(seed).digest("hex");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join("-");
+}

package/dist/session-store.js

@@ -0,0 +1,185 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { MAX_PUSHES_PER_SESSION, SESSIONS_DIR, SESSION_IDLE_TTL_MS, } from "./paths.js";
+const META_FILE = "meta.json";
+const PUSHES_DIR = "pushes";
+function sessionDir(id) {
+    return join(SESSIONS_DIR, id);
+}
+function metaPath(id) {
+    return join(sessionDir(id), META_FILE);
+}
+function pushesDir(id) {
+    return join(sessionDir(id), PUSHES_DIR);
+}
+function ensureSession(id) {
+    const dir = sessionDir(id);
+    if (!existsSync(dir)) {
+        mkdirSync(pushesDir(id), { recursive: true });
+        const meta = {
+            id,
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+            nextIndex: 1,
+            prunedCount: 0,
+            cwd: null,
+            label: null,
+        };
+        writeFileSync(metaPath(id), JSON.stringify(meta, null, 2));
+        return meta;
+    }
+    const existing = readMeta(id);
+    // Backfill new fields on older sessions.
+    if (existing.cwd === undefined)
+        existing.cwd = null;
+    if (existing.label === undefined)
+        existing.label = null;
+    return existing;
+}
+function readMeta(id) {
+    return JSON.parse(readFileSync(metaPath(id), "utf-8"));
+}
+function writeMeta(meta) {
+    writeFileSync(metaPath(meta.id), JSON.stringify(meta, null, 2));
+}
+export function touchSession(id) {
+    const meta = ensureSession(id);
+    meta.lastActivity = Date.now();
+    writeMeta(meta);
+    return meta;
+}
+export function listPushes(id) {
+    if (!existsSync(pushesDir(id)))
+        return [];
+    const files = readdirSync(pushesDir(id))
+        .filter((f) => f.endsWith(".json"))
+        .sort();
+    return files.map((f) => JSON.parse(readFileSync(join(pushesDir(id), f), "utf-8")));
+}
+export function getSessionView(id) {
+    const meta = ensureSession(id);
+    return { meta, pushes: listPushes(id) };
+}
+export function appendPush(sessionId, input) {
+    const meta = ensureSession(sessionId);
+    const push = {
+        id: randomUUID(),
+        index: meta.nextIndex,
+        title: input.title?.trim() || null,
+        kind: input.kind?.trim() || null,
+        html: input.html,
+        createdAt: Date.now(),
+    };
+    const filename = `${String(push.index).padStart(6, "0")}-${push.id}.json`;
+    writeFileSync(join(pushesDir(sessionId), filename), JSON.stringify(push));
+    meta.nextIndex += 1;
+    meta.lastActivity = push.createdAt;
+    pruneOldPushes(sessionId, meta);
+    writeMeta(meta);
+    return push;
+}
+function pruneOldPushes(sessionId, meta) {
+    const files = readdirSync(pushesDir(sessionId))
+        .filter((f) => f.endsWith(".json"))
+        .sort();
+    while (files.length > MAX_PUSHES_PER_SESSION) {
+        const victim = files.shift();
+        if (!victim)
+            break;
+        rmSync(join(pushesDir(sessionId), victim));
+        meta.prunedCount += 1;
+    }
+}
+/**
+ * Delete sessions idle longer than SESSION_IDLE_TTL_MS. Cheap; called from
+ * every push and once at HTTP-server boot.
+ */
+export function sweepIdleSessions(now = Date.now()) {
+    const removed = [];
+    if (!existsSync(SESSIONS_DIR))
+        return { removed };
+    for (const id of readdirSync(SESSIONS_DIR)) {
+        const meta = safeReadMeta(id);
+        if (!meta)
+            continue;
+        if (now - meta.lastActivity > SESSION_IDLE_TTL_MS) {
+            rmSync(sessionDir(id), { recursive: true, force: true });
+            removed.push(id);
+        }
+    }
+    return { removed };
+}
+function safeReadMeta(id) {
+    try {
+        return readMeta(id);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function sessionExists(id) {
+    return existsSync(metaPath(id));
+}
+/** Remove a single push from a session. Returns true if it existed. */
+export function deletePush(sessionId, pushId) {
+    const dir = pushesDir(sessionId);
+    if (!existsSync(dir))
+        return false;
+    for (const f of readdirSync(dir)) {
+        if (f.endsWith(`-${pushId}.json`)) {
+            rmSync(join(dir, f));
+            return true;
+        }
+    }
+    return false;
+}
+/** Delete an entire session from disk. */
+export function deleteSession(id) {
+    const dir = sessionDir(id);
+    if (!existsSync(dir))
+        return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}
+/** First-touch from CLI: ensure session exists without bumping activity. */
+export function registerSession(id) {
+    return ensureSession(id);
+}
+export function updateSessionMeta(id, patch) {
+    const meta = ensureSession(id);
+    if (patch.cwd !== undefined)
+        meta.cwd = patch.cwd;
+    if (patch.label !== undefined)
+        meta.label = patch.label;
+    writeMeta(meta);
+    return meta;
+}
+/**
+ * List every session with derived fields suitable for the index page —
+ * push count, latest push summary, and the meta. Sorted by lastActivity desc.
+ */
+export function listSessionSummaries() {
+    if (!existsSync(SESSIONS_DIR))
+        return [];
+    const summaries = [];
+    for (const id of readdirSync(SESSIONS_DIR)) {
+        try {
+            const meta = ensureSession(id);
+            const pushes = listPushes(id);
+            const last = pushes[pushes.length - 1];
+            summaries.push({
+                ...meta,
+                pushCount: pushes.length,
+                lastPushTitle: last?.title ?? null,
+                lastPushKind: last?.kind ?? null,
+                lastPushAt: last?.createdAt ?? null,
+            });
+        }
+        catch {
+            /* skip corrupt session dir */
+        }
+    }
+    summaries.sort((a, b) => b.lastActivity - a.lastActivity);
+    return summaries;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ammduncan/easel",
+  "version": "0.2.0",
+  "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",
+  "author": "Ammiel Yawson",
+  "homepage": "https://github.com/AmmDuncan/easel#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmmDuncan/easel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AmmDuncan/easel/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "claude-desktop",
+    "agent-ui",
+    "browser-display",
+    "live-feed"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "easel": "bin/easel"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "scripts/easel-session-id.mjs",
+    "skills/",
+    "README.md",
+    "LICENCE"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/copy-client.mjs",
+    "start": "node dist/cli.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "express": "^4.21.2",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.2"
+  }
+}

package/scripts/easel-session-id.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// easel-session-id.mjs — SessionStart hook for Claude Code.
+//
+// Does three things:
+//   1. Captures Claude's session_id (passed as JSON on stdin per the hooks
+//      spec) into ~/.easel/hook/cc-session-<ppid>.txt so the easel MCP
+//      adapter can resolve it by parent PID.
+//   2. Outputs `additionalContext` JSON so the agent always sees the easel
+//      conventions at the start of every chat — even when the chat never
+//      triggers the using-easel skill via content shape.
+//   3. Checks (cached, every 24h) whether the local install is behind
+//      origin/main and appends an "updates available" line.
+//
+// Ported from bash to drop the jq dependency.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const HOME = homedir();
+const LEGACY_ROOT = join(HOME, ".claude-display");
+const DATA_ROOT = join(HOME, ".easel");
+
+// One-time migration from the project's prior name. Idempotent.
+if (existsSync(LEGACY_ROOT) && !existsSync(DATA_ROOT)) {
+  try {
+    renameSync(LEGACY_ROOT, DATA_ROOT);
+  } catch {
+    // best-effort; downstream mkdir handles it
+  }
+}
+
+function readStdinSync() {
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function parseSessionId(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    return typeof obj?.session_id === "string" ? obj.session_id : "";
+  } catch {
+    return "";
+  }
+}
+
+const input = readStdinSync();
+const sessionId = parseSessionId(input);
+
+if (sessionId) {
+  const hookDir = join(DATA_ROOT, "hook");
+  mkdirSync(hookDir, { recursive: true });
+  writeFileSync(join(hookDir, `cc-session-${process.ppid}.txt`), `${sessionId}\n`);
+}
+
+// --- staleness check (cached, every 24h) ------------------------------------
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INSTALL_DIR = resolve(__dirname, "..");
+const CACHE_FILE = join(DATA_ROOT, "update-check");
+const NOW = Math.floor(Date.now() / 1000);
+
+function git(args, opts = {}) {
+  const r = spawnSync("git", ["-C", INSTALL_DIR, ...args], {
+    encoding: "utf-8",
+    timeout: opts.timeoutMs ?? 800,
+  });
+  if (r.status !== 0) return "";
+  return (r.stdout ?? "").trim();
+}
+
+let localSha = "";
+let remoteSha = "";
+if (existsSync(join(INSTALL_DIR, ".git"))) {
+  localSha = git(["rev-parse", "HEAD"]);
+
+  let lastCheck = 0;
+  let lastRemote = "";
+  if (existsSync(CACHE_FILE)) {
+    try {
+      const [line1 = "", line2 = ""] = readFileSync(CACHE_FILE, "utf-8").split("\n");
+      lastCheck = Number.parseInt(line1, 10) || 0;
+      lastRemote = line2.trim();
+    } catch {
+      // ignore — cache miss is fine
+    }
+  }
+
+  if (NOW - lastCheck > 86400) {
+    const lsRemote = git(["ls-remote", "origin", "main"], { timeoutMs: 2000 });
+    remoteSha = lsRemote.split(/\s+/)[0] ?? "";
+    if (remoteSha) {
+      try {
+        mkdirSync(DATA_ROOT, { recursive: true });
+        writeFileSync(CACHE_FILE, `${NOW}\n${remoteSha}\n`);
+      } catch {
+        // best-effort cache write
+      }
+    }
+  } else {
+    remoteSha = lastRemote;
+  }
+}
+
+const updateLine =
+  localSha && remoteSha && localSha !== remoteSha
+    ? "\n\nUPDATE AVAILABLE — local easel is behind origin/main. Run `easel update` to pull, build, and re-wire setup. Mention this to the user once if they bring up easel; otherwise it's just FYI."
+    : "";
+
+// --- additionalContext reminder ---------------------------------------------
+const reminder = `easel is registered as an MCP for this session. Tools available:
+mcp__easel__push, mcp__easel__open, mcp__easel__config, mcp__easel__label.
+
+CONVENTION — label every session early.
+Call mcp__easel__label({ label: "<short human name>" }) as soon as the
+user's intent is clear in this chat, and NO LATER than your first
+mcp__easel__push call. Sessions without labels show up as the cwd
+basename in the switcher (e.g. "dvla"), which is unfindable when
+multiple tabs are open. Re-call label when the work's theme shifts
+meaningfully. Format: 1–8 words, sentence case, no trailing punctuation,
+mention the artefact not the verb (good: "RegistrationNumberInput
+extraction"; bad: "Extracting RegistrationNumberInput").
+
+When pushing visual content (mockup, diagram, comparison, long
+explanation, diff, multi-step status), use mcp__easel__push proactively
+— do not ask permission. Reply in chat with one line: "pushed to easel
+↗ — #N". The full style guide lives in the using-easel skill.${updateLine}`;
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: reminder,
+    },
+  }),
+);