@bakapiano/ccsm 0.3.0 → 0.5.0

package/CLAUDE.md

@@ -34,6 +34,7 @@ D:\ccsm\
 ├── lib\
 │   ├── sessions.js          # reads ~/.claude/sessions/*.json + cross-checks live PIDs (tasklist)
 │   │                        # + pulls last ai-title from ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl
+│   │                        # + listRecentSessions(limit, offset) returns paged {recent, total}
 │   ├── snapshot.js          # save/load/rotate/restore — restore = launch one wt window per session
 │   ├── workspace.js         # workspace = subfolder under workDir holding repo clones;
 │   │                        # "in use" = any live session's cwd is at/under the workspace path
@@ -41,6 +42,7 @@ D:\ccsm\
 │   │                        # path.resolve()s cwd; throws if cwd doesn't exist
 │   ├── focus.js             # PowerShell + Win32 — listWindowsOf, focusByHwnd, focusByPid,
 │   │                        # focusNewlyOpenedHwnd (HWND-diff for auto-focus on launch)
+│   ├── favorites.js         # user-pinned sessions, ~/.ccsm/favorites.json keyed by sessionId
 │   └── config.js            # loadConfig/saveConfig with defaults
 ├── public\
 │   ├── index.html, app.js, styles.css   # vanilla, auto-refresh every 5s
@@ -49,7 +51,9 @@ D:\ccsm\
 ~/.ccsm/                     # or $CCSM_HOME
 ├── config.json              # source of truth
 ├── snapshot.json            # latest snapshot, rewritten every 60s
-└── snapshots/               # rotating history (default keep=30)
+├── snapshots/               # rotating history (default keep=30)
+├── favorites.json           # { [sessionId]: { sessionId, cwd, title, gitBranch, addedAt } }
+└── browser-profile/         # Edge/Chrome --user-data-dir when browserMode=app
 ```
 
 On first run, if a legacy `<repo>/data/` directory exists and `~/.ccsm/` is empty, `lib/config.js` copies the old data over (one-time, idempotent). The legacy dir is left in place — clean up manually after verifying.
@@ -88,7 +92,11 @@ The alternative ("one repo per workspace") was explicitly rejected — don't ref
 | POST | `/api/sessions/new` | body `{repos, workspace?, launch?}` — picks/creates ws, clones missing repos, launches wt |
 | POST | `/api/sessions/finder` | opens a wt with `claude` in `D:\ccsm` and the `finderPrompt` as opening message |
 | POST | `/api/sessions/:id/resume` | body `{cwd}` — launches `wt -d <cwd> claude --resume <id>` |
-| POST | `/api/sessions/:id/focus` | walks up the claude PID parent chain to find the wt window, raises it via SetForegroundWindow |
+| GET | `/api/sessions/recent` | recently-used sessions from `~/.claude/projects/*/*.jsonl` mtimes, excluding live ids · query `?limit=15&offset=0` for pagination · returns `{recent, total, limit, offset}` |
+| POST | `/api/sessions/:id/focus` | matches a wt window by title (cleaned of leading status glyphs) against the session's ai-title; falls back to PID-parent walk if no unique match |
+| GET | `/api/favorites` | array of pinned sessions sorted by `addedAt` desc |
+| POST | `/api/favorites/:id` | star a session; body `{cwd, title, gitBranch?, label?}` (snapshot of current row data so the favorite stays meaningful after the jsonl is gone) |
+| DELETE | `/api/favorites/:id` | unstar |
 | GET | `/api/terminals` | enumerate built-in terminal kinds + their process names |
 | GET | `/api/health` | sanity ping |
 
@@ -112,6 +120,8 @@ ccsm uses variant 1 and always `path.resolve()`s the cwd first — defends again
 
 **Don't test wt launching via `node -e "..."` inside `bash -c`.** Backslashes get eaten by shell quoting and the JS string ends up malformed. Write a `.js` file and `node file.js` instead.
 
+**focusBySession — title-based wt window matching.** Walking up the claude.exe PID parent chain and taking `MainWindowHandle` of the wt process *always* returns the same canonical window in modern multi-window single-process wt — clicking different sessions all focused the same window. `focusBySession` instead lists all visible wt windows (`EnumWindows` filtered by process name), strips the leading wt status glyph (`✳ `, `⠐ `, `⠠ ` …) and compares to the session's ai-title. Falls back to title-substring, then cwd-basename, then the old PID-parent walk when no unique match — at least the user sees *some* wt window even if it's the wrong tab. Caveat: for sessions sitting in an inactive tab of a multi-tab wt window, the window title shows the *active* tab's title — so we can't find them by title alone and the fallback is wrong-tab.
+
 **Focus helper (`lib/focus.js`).** One `powershell.exe -EncodedCommand <base64>` invocation per call, dispatched by `CCSM_FOCUS_MODE` env var into modes `list` (enumerate visible top-level windows owned by a process name), `focus-hwnd` (activate a specific HWND), `focus-pid` (walk parent chain to MainWindowHandle then activate). Encoded as UTF-16-LE-base64 — passing the C# block via stdin to `-Command -` silently produces no output, so we don't. Three gotchas baked in:
 1. C# `out _` discard breaks PowerShell 5.1's bundled C# compiler — use a named `uint dummy`.
 2. Windows blocks background processes from `SetForegroundWindow` — synthesize an Alt-key down/up via `keybd_event 0x12` first ("Alt-key trick") to qualify our process. Without it, `activated` returns false even though the window is found.
@@ -127,10 +137,58 @@ ccsm uses variant 1 and always `path.resolve()`s the cwd first — defends again
 
 **`projectSlugForCwd`.** The path-to-slug mapping is `cwd.replace(/[:\\]/g, '-')`, e.g. `D:\ccsm` → `D--ccsm`, `C:\Users\foo` → `C--Users-foo`, `D:\` → `D--`.
 
+## Frontend design language
+
+The UI deliberately copies **claude.ai's** calm light aesthetic — warm cream surfaces, generous spacing, soft borders, single Claude-orange accent. Don't dark-mode-ify or chrome-ify.
+
+**Palette** (CSS vars in `public/styles.css`):
+- `--bg`            `#faf9f5`  warm cream page background
+- `--bg-elev`       `#ffffff`  card surfaces
+- `--sidebar-bg`    `#f3f0e8`  slightly darker cream for the rail
+- `--border`        `#e8e3d5`  hairlines
+- `--ink`           `#1a1815`  body text (warm near-black)
+- `--ink-mid`       `#534e44`  secondary
+- `--ink-muted`     `#8a8475`  meta
+- `--accent`        `#c45f3f`  Claude warm orange — for primary actions, focus rings, active states ONLY
+- Status: green `#4a8a4a` idle · yellow `#c4892b` busy (pulsing) · red `#b73f3f` danger
+
+**Type**:
+- Body / headings: **Geist** (Google Fonts, 300–700). No Fraunces / no italic display.
+- Mono: **JetBrains Mono** for paths, PIDs, sessionIds, branch tags, timestamps in meta.
+- Always `font-variant-numeric: tabular-nums` on numeric cells.
+
+**Layout**:
+- **Sidebar** (collapsible, ~232px ↔ ~60px, state in `localStorage["ccsm.sidebar-collapsed"]`):
+  - top: brand mark (orange rounded square) + `ccsm.` wordmark
+  - mid: 3 nav items (Sessions / Launch / Configure) with stroke icons + label + optional badge
+  - divider + utility items (Refresh, Ask Claude)
+  - footer: collapse toggle (chevron flips on collapse via CSS rotate)
+- **Main column**: page header (title + subtitle + meta row of port/terminal/clock) → content cards → footer status line
+- Cards: `.card` (white, 10px radius, very soft `--shadow`), `.card-head` with title+meta, `.card-body` with optional `.card-body-flush` for tables.
+- Tables: wrapped in `.table-scroll` (`overflow-x: auto`, min-width 760px) so narrow viewports scroll horizontally instead of cramping.
+
+**Animation**:
+- **Don't re-animate on refresh.** Rows have a one-shot staggered fade-in animation. `app.js` `markRendered(tableId)` adds `.no-anim` to the tbody after the first render via double `requestAnimationFrame`, so subsequent 5-second auto-refreshes don't restage every row (would strobe).
+- Panel switch: 0.35s `panel-in` fade-up.
+- Tab indicator: orange left bar on active sidebar item (`::before`).
+- Busy status mark: green-pulse via `box-shadow` keyframes.
+
+**Star (favorites) UI**:
+- Star button sits **inside the title cell**, right next to the title text (not in its own column). Outline-style by default at 55% opacity; row-hover bumps to 100%; favorited state fills with the accent color.
+- Click is delegated at the table level (`button[data-star]`). Toggle is **optimistic**: `state.favorites` updates and re-renders all 3 tables before the network call returns; failure shows a toast.
+- Backend snapshots `cwd / title / gitBranch` into `favorites.json` so the favorite is still meaningful after the source jsonl is gone.
+
+**No emoji in the UI** unless the user typed it (e.g. wt status glyphs in session titles). Use inline SVG icons everywhere (line stroke, 1.5–2px) so they take `currentColor` and live with the type weight.
+
+## Lifecycle: server tied to browser window
+
+When the user launches via `npx @bakapiano/ccsm` from an interactive terminal (`process.stdout.isTTY === true`) AND `browserMode === 'app'`, the server keeps the spawned Edge/Chrome child handle and listens for its `exit` event. When the user closes the chromeless window, msedge.exe (running with its own `--user-data-dir=<DATA_DIR>/browser-profile` process group) exits, our hook fires `process.exit(0)`, and the terminal returns to a prompt. Headless / `nohup` launches don't get this hook (no TTY) and stay running.
+
 ## Extending
 
 When adding features, the natural extension points:
 - New REST routes: `server.js` (keep them under `/api/*`, use `asyncH` wrapper).
-- Frontend section: add a `<section class="panel">` in `public/index.html` and a render function in `public/app.js`.
+- Frontend section: add a `<section class="card">` in `public/index.html` and a render function in `public/app.js`. Use `markRendered(tableId)` after the first render to suppress refresh strobing.
+- Persistent user data: drop a JSON file under `~/.ccsm/` (like `favorites.json`) and wrap with a small lib module — config.js / favorites.js pattern.
 - Workspace lifecycle (delete, rename): `lib/workspace.js`.
 - Different launch modes (e.g., stacked tabs): `lib/launcher.js` — but check first whether the "one window per session" decision still holds.

package/lib/favorites.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// User-pinned ("favorited") sessions. Stored as a JSON object keyed by
+// sessionId at $DATA_DIR/favorites.json. Each entry captures enough
+// metadata (cwd, title, gitBranch) to render the row even after the
+// session's jsonl is gone — the entry is best-effort archival.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { DATA_DIR } = require('./config');
+
+const FAVORITES_PATH = path.join(DATA_DIR, 'favorites.json');
+
+async function loadFavorites() {
+  try {
+    const raw = await fs.readFile(FAVORITES_PATH, 'utf8');
+    const obj = JSON.parse(raw);
+    return obj && typeof obj === 'object' && !Array.isArray(obj) ? obj : {};
+  } catch (e) {
+    if (e.code === 'ENOENT') return {};
+    throw e;
+  }
+}
+
+async function saveFavorites(favs) {
+  await fs.writeFile(FAVORITES_PATH, JSON.stringify(favs, null, 2));
+}
+
+async function listFavorites() {
+  const favs = await loadFavorites();
+  return Object.values(favs).sort((a, b) => (b.addedAt || 0) - (a.addedAt || 0));
+}
+
+async function addFavorite(sessionId, info = {}) {
+  if (!sessionId) throw new Error('addFavorite: sessionId required');
+  const favs = await loadFavorites();
+  const existing = favs[sessionId];
+  favs[sessionId] = existing
+    ? { ...existing, ...info, sessionId }
+    : {
+        sessionId,
+        cwd: info.cwd || null,
+        title: info.title || null,
+        gitBranch: info.gitBranch || null,
+        label: info.label || null,
+        addedAt: Date.now(),
+      };
+  await saveFavorites(favs);
+  return favs[sessionId];
+}
+
+async function removeFavorite(sessionId) {
+  const favs = await loadFavorites();
+  if (!(sessionId in favs)) return false;
+  delete favs[sessionId];
+  await saveFavorites(favs);
+  return true;
+}
+
+async function hasFavorite(sessionId) {
+  const favs = await loadFavorites();
+  return sessionId in favs;
+}
+
+module.exports = {
+  loadFavorites,
+  saveFavorites,
+  listFavorites,
+  addFavorite,
+  removeFavorite,
+  hasFavorite,
+  FAVORITES_PATH,
+};

package/lib/focus.js

@@ -192,6 +192,63 @@ async function focusByPid(pid) {
   return await runPsHelper('focus-pid', n);
 }
 
+// Strip the leading wt status glyph + whitespace ("✳ ", "⠐ ", "⠠ " etc) so
+// the title compares cleanly. wt prefixes the tab title with a Braille-style
+// progress glyph or a sparkle/asterisk depending on activity.
+function cleanWtTitle(t) {
+  return String(t || '').replace(/^[^\w一-鿿]+/, '').trim();
+}
+
+// Best-effort: focus the wt window that belongs to a specific session.
+// Modern wt is single-process multi-window, so walking from claude.exe PID
+// up to wt.exe + taking MainWindowHandle always returns the same canonical
+// window regardless of which tab the session is actually in. Instead we
+// list all wt windows and match by tab title against the session's AI
+// title / cwd basename.
+async function focusBySession({ pid, sessionId, title, cwd }) {
+  const procName = 'WindowsTerminal.exe';
+  const cands = await listWindowsOf(procName);
+
+  const cleanedTitle = title ? cleanWtTitle(title) : '';
+  const cwdBase = cwd ? require('node:path').basename(cwd) : '';
+
+  // 1. Exact match on cleaned ai-title
+  if (cleanedTitle) {
+    const exact = cands.filter((w) => cleanWtTitle(w.title) === cleanedTitle);
+    if (exact.length === 1) {
+      const r = await focusByHwnd(exact[0].hwnd);
+      return { ...r, matchedBy: 'title-exact', hwnd: exact[0].hwnd, windowTitle: exact[0].title };
+    }
+  }
+
+  // 2. Title substring match (some shells append " - <cwd>" etc)
+  if (cleanedTitle) {
+    const subs = cands.filter((w) => w.title.includes(cleanedTitle));
+    if (subs.length === 1) {
+      const r = await focusByHwnd(subs[0].hwnd);
+      return { ...r, matchedBy: 'title-substring', hwnd: subs[0].hwnd, windowTitle: subs[0].title };
+    }
+  }
+
+  // 3. Match by cwd basename (workspace name shows up in title for fresh launches)
+  if (cwdBase) {
+    const byCwd = cands.filter((w) => w.title.includes(cwdBase));
+    if (byCwd.length === 1) {
+      const r = await focusByHwnd(byCwd[0].hwnd);
+      return { ...r, matchedBy: 'cwd-basename', hwnd: byCwd[0].hwnd, windowTitle: byCwd[0].title };
+    }
+  }
+
+  // 4. Fall back to PID parent-chain walk (returns the wt process's
+  //    canonical MainWindowHandle — may be the wrong window when wt is
+  //    multi-window single-process, but better than nothing).
+  if (pid) {
+    const r = await focusByPid(pid);
+    return { ...r, matchedBy: 'pid-fallback', ambiguous: true };
+  }
+  return { ok: false, error: 'no match by title/cwd and no pid given', matchedBy: 'none' };
+}
+
 async function focusByHwnd(hwnd) {
   return await runPsHelper('focus-hwnd', hwnd);
 }
@@ -228,6 +285,7 @@ async function focusNewlyOpenedHwnd(beforeHwnds, processName, opts = {}) {
 
 module.exports = {
   focusByPid,
+  focusBySession,
   focusByHwnd,
   listWindowsOf,
   snapshotWindowsOf,

package/lib/sessions.js

@@ -110,8 +110,161 @@ async function listSessions() {
     .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
 }
 
+// Pull cwd/title/firstTimestamp from a jsonl by reading the head (cwd lives in
+// any user/assistant/attachment line) and tailing for the last ai-title.
+async function readJsonlMetadata(jsonlPath) {
+  let fd;
+  try {
+    fd = await fs.open(jsonlPath, 'r');
+    const stat = await fd.stat();
+    if (stat.size === 0) return { size: 0 };
+
+    const HEAD = Math.min(stat.size, 128 * 1024);
+    const headBuf = Buffer.alloc(HEAD);
+    await fd.read(headBuf, 0, HEAD, 0);
+    const headText = headBuf.toString('utf8');
+
+    let cwd = null;
+    let gitBranch = null;
+    let firstTimestamp = null;
+    for (const line of headText.split('\n')) {
+      if (!line) continue;
+      if (cwd && firstTimestamp) break;
+      if (!line.includes('"cwd"') && !line.includes('"timestamp"')) continue;
+      try {
+        const obj = JSON.parse(line);
+        if (obj.cwd && !cwd) cwd = obj.cwd;
+        if (obj.gitBranch && !gitBranch) gitBranch = obj.gitBranch;
+        if (obj.timestamp && !firstTimestamp) firstTimestamp = obj.timestamp;
+      } catch {}
+    }
+
+    const TAIL = Math.min(stat.size, 512 * 1024);
+    const tailBuf = Buffer.alloc(TAIL);
+    await fd.read(tailBuf, 0, TAIL, Math.max(0, stat.size - TAIL));
+    const tailText = tailBuf.toString('utf8');
+    let title = null;
+    const tailLines = tailText.split('\n');
+    for (let i = tailLines.length - 1; i >= 0; i--) {
+      if (!tailLines[i].includes('"type":"ai-title"')) continue;
+      try {
+        const obj = JSON.parse(tailLines[i]);
+        if (obj.aiTitle) { title = obj.aiTitle; break; }
+      } catch {}
+    }
+
+    return { cwd, gitBranch, firstTimestamp, title, size: stat.size };
+  } catch {
+    return {};
+  } finally {
+    if (fd) await fd.close().catch(() => {});
+  }
+}
+
+// Cheap enumeration of jsonl session files — file stats only, no content read.
+async function enumerateRecentCandidates({ excludeIds = null } = {}) {
+  let projectDirs;
+  try {
+    projectDirs = await fs.readdir(PROJECTS_DIR);
+  } catch {
+    return [];
+  }
+
+  const candidates = [];
+  for (const slugDir of projectDirs) {
+    const dirPath = path.join(PROJECTS_DIR, slugDir);
+    let entries;
+    try {
+      entries = await fs.readdir(dirPath);
+    } catch {
+      continue;
+    }
+    for (const file of entries) {
+      if (!file.endsWith('.jsonl')) continue;
+      const sessionId = file.slice(0, -'.jsonl'.length);
+      if (excludeIds && excludeIds.has(sessionId)) continue;
+      const fullPath = path.join(dirPath, file);
+      try {
+        const stat = await fs.stat(fullPath);
+        if (stat.size === 0) continue;
+        candidates.push({
+          sessionId,
+          slug: slugDir,
+          jsonlPath: fullPath,
+          mtime: stat.mtimeMs,
+        });
+      } catch {}
+    }
+  }
+
+  candidates.sort((a, b) => b.mtime - a.mtime);
+  return candidates;
+}
+
+// Paginated, sorted by mtime desc. Returns { recent, total } so callers can
+// render pagination controls. Cheap stat-only enumeration happens for ALL
+// candidates; expensive jsonl-content reads only on the page slice.
+async function listRecentSessions({ limit = 50, offset = 0, excludeIds = null } = {}) {
+  const candidates = await enumerateRecentCandidates({ excludeIds });
+  const total = candidates.length;
+  const page = candidates.slice(offset, offset + limit);
+
+  const results = await Promise.all(
+    page.map(async (c) => {
+      const meta = await readJsonlMetadata(c.jsonlPath);
+      const firstTs = meta.firstTimestamp ? Date.parse(meta.firstTimestamp) : null;
+      return {
+        sessionId: c.sessionId,
+        cwd: meta.cwd || null,
+        title: meta.title || null,
+        gitBranch: meta.gitBranch || null,
+        updatedAt: c.mtime,
+        startedAt: Number.isFinite(firstTs) ? firstTs : null,
+        jsonlPath: c.jsonlPath,
+      };
+    })
+  );
+
+  // Drop entries with no cwd — can't resume without one. Adjust total
+  // accordingly is tricky (would need to enrich all), so we don't — the
+  // total is the upper bound of resumable + non-resumable.
+  return { recent: results.filter((r) => r.cwd), total };
+}
+
+// Look up metadata for a specific sessionId by scanning the projects dir.
+// Used by /api/favorites to display rich metadata for archived sessions.
+async function findSessionMetadata(sessionId) {
+  let projectDirs;
+  try {
+    projectDirs = await fs.readdir(PROJECTS_DIR);
+  } catch {
+    return null;
+  }
+  for (const slugDir of projectDirs) {
+    const fullPath = path.join(PROJECTS_DIR, slugDir, `${sessionId}.jsonl`);
+    try {
+      const stat = await fs.stat(fullPath);
+      if (stat.size === 0) continue;
+      const meta = await readJsonlMetadata(fullPath);
+      const firstTs = meta.firstTimestamp ? Date.parse(meta.firstTimestamp) : null;
+      return {
+        sessionId,
+        cwd: meta.cwd || null,
+        title: meta.title || null,
+        gitBranch: meta.gitBranch || null,
+        updatedAt: stat.mtimeMs,
+        startedAt: Number.isFinite(firstTs) ? firstTs : null,
+        jsonlPath: fullPath,
+      };
+    } catch {}
+  }
+  return null;
+}
+
 module.exports = {
   listSessions,
+  listRecentSessions,
+  findSessionMetadata,
   projectSlugForCwd,
   getLiveClaudePids,
   SESSIONS_DIR,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakapiano/ccsm",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Claude Code Session Manager — Windows web UI to manage many concurrent claude sessions: live list, snapshot/restore, focus existing window, new session in an isolated workspace with repo clones",
   "license": "MIT",
   "main": "server.js",