mulmoclaude 0.1.0

package/server/api/routes/sessions.ts

@@ -0,0 +1,294 @@
+import { Router, Request, Response } from "express";
+import fs from "fs";
+import { readdir, stat } from "fs/promises";
+import { readTextSafe } from "../../utils/files/safe.js";
+import path from "path";
+import { workspacePath } from "../../workspace/workspace.js";
+import { WORKSPACE_PATHS } from "../../workspace/paths.js";
+import { readSessionMeta as readSessionMetaIO, readSessionJsonl, sessionJsonlAbsPath, sessionMetaAbsPath } from "../../utils/files/session-io.js";
+import { readManifest } from "../../workspace/chat-index/indexer.js";
+import { resolveWithinRoot } from "../../utils/files/safe.js";
+import type { ChatIndexEntry } from "../../workspace/chat-index/types.js";
+import { markRead, getSession } from "../../events/session-store/index.js";
+import { notFound } from "../../utils/httpError.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { EVENT_TYPES } from "../../../src/types/events.js";
+import type { SessionOrigin } from "../../../src/types/session.js";
+import { env } from "../../system/env.js";
+import { ONE_DAY_MS } from "../../utils/time.js";
+import { encodeCursor, parseCursor, sessionChangeMs } from "./sessionsCursor.js";
+
+interface SessionMeta {
+  roleId: string;
+  startedAt: string;
+  firstUserMessage?: string;
+  hasUnread?: boolean;
+  origin?: SessionOrigin;
+}
+
+async function readSessionMeta(__chatDir: string, id: string): Promise<SessionMeta | null> {
+  // Try new-style .json meta first
+  const meta = await readSessionMetaIO(id);
+  if (meta?.roleId && meta?.startedAt) {
+    return meta as SessionMeta;
+  }
+  // Legacy: read first line of .jsonl
+  const jsonl = await readSessionJsonl(id);
+  if (jsonl) {
+    const first = jsonl.split("\n").find(Boolean);
+    if (first) {
+      try {
+        const parsed = JSON.parse(first);
+        if (parsed.roleId && parsed.startedAt) return parsed;
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return null;
+}
+
+export interface SessionSummary {
+  id: string;
+  roleId: string;
+  startedAt: string;
+  // ISO timestamp of the jsonl file's most recent mtime — i.e. the
+  // last time the session had an event appended. Clients sort the
+  // sidebar history list by this so active sessions float to the top.
+  updatedAt: string;
+  preview: string;
+  // Populated when the chat indexer has produced a summary for this
+  // session. The frontend renders `summary` as a smaller second line
+  // under the preview in the history popup. See #123.
+  summary?: string;
+  keywords?: string[];
+  // Where this session originated (#486). Missing = "human".
+  origin?: SessionOrigin;
+  // Live state from the in-memory session store. Absent when the
+  // session has no active entry in the store (i.e. idle / historical).
+  isRunning?: boolean;
+  hasUnread?: boolean;
+  statusMessage?: string;
+}
+
+// Public response envelope for GET /api/sessions (issue #205).
+//
+// `cursor`     — opaque string clients echo back as `?since=` on the
+//                next call to receive only sessions that have changed.
+// `deletedIds` — always `[]` for now (no session-delete code path
+//                exists yet). Kept in the shape so the client already
+//                merges it; when deletion lands, populating this will
+//                be a server-only change.
+interface SessionsResponse {
+  sessions: SessionSummary[];
+  cursor: string;
+  deletedIds: string[];
+}
+
+interface SessionsQuery {
+  since?: string;
+}
+
+const router = Router();
+
+// Sessions older than this are excluded from the listing. Set
+// SESSIONS_LIST_WINDOW_DAYS to override (0 = no cutoff).
+const WINDOW_MS = env.sessionsListWindowDays * ONE_DAY_MS;
+
+// Read the full session list off disk. Each row carries its
+// `changeMs` — the later of the jsonl mtime and the chat-index
+// `indexedAt` — so the handler can filter against `?since=` and
+// compute the new cursor without re-statting anything.
+export async function loadAllSessions(): Promise<{ summary: SessionSummary; changeMs: number }[]> {
+  const chatDir = WORKSPACE_PATHS.chat;
+  const manifest = await readManifest(workspacePath);
+  const indexById = new Map<string, ChatIndexEntry>(manifest.entries.map((e) => [e.id, e]));
+  const cutoff = WINDOW_MS > 0 ? Date.now() - WINDOW_MS : 0;
+
+  const files = (await readdir(chatDir)).filter((f) => f.endsWith(".jsonl"));
+  const rows = await Promise.all(
+    files.map(async (file) => {
+      const id = file.replace(".jsonl", "");
+      try {
+        // stat only — no readFile on .jsonl content
+        const fileStat = await stat(sessionJsonlAbsPath(id));
+        if (cutoff > 0 && fileStat.mtimeMs < cutoff) return null;
+
+        const meta = await readSessionMeta(chatDir, id);
+        if (!meta) return null;
+
+        // The meta sidecar bumps its mtime on hasUnread / origin
+        // writes — feed it into changeMs so cursor-based refetches
+        // pick up drains of background generations (which only touch
+        // meta, not the jsonl). Missing stat (brand-new session
+        // before its first meta write) contributes 0.
+        const metaMtimeMs = await stat(sessionMetaAbsPath(id))
+          .then((s) => s.mtimeMs)
+          .catch(() => 0);
+
+        const indexEntry = indexById.get(id);
+        // Prefer AI title → meta.firstUserMessage → empty.
+        // `summary` and `keywords` are spread conditionally
+        // to respect the server tsconfig's
+        // exactOptionalPropertyTypes.
+        const preview = indexEntry?.title ?? meta.firstUserMessage ?? "";
+
+        const live = getSession(id);
+        const summary: SessionSummary = {
+          id,
+          roleId: meta.roleId,
+          startedAt: meta.startedAt,
+          updatedAt: new Date(fileStat.mtimeMs).toISOString(),
+          preview,
+          hasUnread: live?.hasUnread ?? meta.hasUnread ?? false,
+        };
+        if (meta.origin) summary.origin = meta.origin;
+        if (indexEntry?.summary !== undefined) summary.summary = indexEntry.summary;
+        if (indexEntry?.keywords !== undefined) summary.keywords = indexEntry.keywords;
+        if (live) {
+          // Background generations (image/audio/movie) keep the session
+          // "busy" even when the agent turn has ended, so the sidebar
+          // indicator stays lit across view navigation.
+          summary.isRunning = live.isRunning || Object.keys(live.pendingGenerations).length > 0;
+          summary.statusMessage = live.statusMessage;
+        }
+        return {
+          summary,
+          changeMs: sessionChangeMs(fileStat.mtimeMs, indexEntry?.indexedAt, metaMtimeMs),
+        };
+      } catch {
+        return null;
+      }
+    }),
+  );
+  return rows.filter((r): r is { summary: SessionSummary; changeMs: number } => r !== null);
+}
+
+router.get(API_ROUTES.sessions.list, async (req: Request<object, SessionsResponse, object, SessionsQuery>, res: Response<SessionsResponse>) => {
+  try {
+    const sinceMs = parseCursor(req.query.since);
+    const rows = await loadAllSessions();
+
+    // Cursor = max(changeMs) across every visible session, regardless
+    // of whether it's in the diff. Echoing the same cursor back on an
+    // empty diff (nothing changed since `?since=`) is fine; the
+    // client no-ops.
+    const maxChangeMs = rows.reduce((acc, r) => Math.max(acc, r.changeMs), 0);
+
+    const filtered = sinceMs > 0 ? rows.filter((r) => r.changeMs > sinceMs) : rows;
+
+    const sessions = filtered.map((r) => r.summary);
+    sessions.sort((a, b) => {
+      const byUpdated = new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+      if (byUpdated !== 0) return byUpdated;
+      return new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime();
+    });
+
+    res.json({
+      sessions,
+      cursor: encodeCursor(maxChangeMs),
+      // No session-delete code path exists today — issue #205 picked
+      // approach A (tombstones) so the client already merges this
+      // field; populating it becomes a server-only change when
+      // deletion lands.
+      deletedIds: [],
+    });
+  } catch {
+    res.json({ sessions: [], cursor: encodeCursor(0), deletedIds: [] });
+  }
+});
+
+interface SessionIdParams {
+  id: string;
+}
+
+interface SessionErrorResponse {
+  error: string;
+}
+
+router.get(API_ROUTES.sessions.detail, async (req: Request<SessionIdParams>, res: Response<unknown[] | SessionErrorResponse>) => {
+  const { id } = req.params;
+  const chatDir = WORKSPACE_PATHS.chat;
+  try {
+    const meta = await readSessionMeta(chatDir, id);
+    const content = await readSessionJsonl(id);
+    if (!content) {
+      notFound(res, `Session ${id} not found`);
+      return;
+    }
+    const entries = (
+      await Promise.all(
+        content
+          .split("\n")
+          .filter(Boolean)
+          .map(async (line) => {
+            try {
+              const entry = JSON.parse(line);
+              // Skip legacy metadata entries now stored in .json
+              if (entry.type === EVENT_TYPES.sessionMeta || entry.type === EVENT_TYPES.claudeSessionId) return null;
+              // For presentMulmoScript results, re-read the script from disk
+              if (
+                entry.source === "tool" &&
+                entry.type === EVENT_TYPES.toolResult &&
+                entry.result?.toolName === "presentMulmoScript" &&
+                entry.result?.data?.filePath
+              ) {
+                try {
+                  // Realpath-based traversal check defeats symlink
+                  // escapes — see resolveWithinRoot in utils/fs.ts.
+                  // Resolve the stories dir's realpath so the
+                  // boundary check works even when stories/ itself
+                  // is a legitimate symlink to another disk.
+                  const storiesDir = path.resolve(WORKSPACE_PATHS.stories);
+                  let storiesReal: string;
+                  try {
+                    storiesReal = fs.realpathSync(storiesDir);
+                  } catch {
+                    return entry;
+                  }
+                  const scriptRelPath: string = entry.result.data.filePath;
+                  if (path.isAbsolute(scriptRelPath)) return entry;
+                  // Strip optional "stories/" prefix so the
+                  // remainder is relative to storiesReal.
+                  const relFromStories = scriptRelPath.startsWith("stories/") ? scriptRelPath.slice("stories/".length) : scriptRelPath;
+                  const scriptPath = resolveWithinRoot(storiesReal, relFromStories);
+                  if (!scriptPath) return entry;
+                  const scriptJson = (await readTextSafe(scriptPath)) ?? "";
+                  return {
+                    ...entry,
+                    result: {
+                      ...entry.result,
+                      data: {
+                        ...entry.result.data,
+                        script: JSON.parse(scriptJson),
+                      },
+                    },
+                  };
+                } catch {
+                  // file missing — return original entry
+                }
+              }
+              return entry;
+            } catch {
+              return null;
+            }
+          }),
+      )
+    ).filter(Boolean);
+    // Prepend metadata as session_meta entry for the frontend
+    const result = meta ? [{ type: EVENT_TYPES.sessionMeta, ...meta }, ...entries] : entries;
+    res.json(result);
+  } catch {
+    notFound(res, "Session not found");
+  }
+});
+
+// Mark a session as read (clears the hasUnread flag in the session store).
+// Awaits persistence so the response only arrives after the disk write
+// completes — prevents the client from refetching stale hasUnread values.
+router.post(API_ROUTES.sessions.markRead, async (req: Request<SessionIdParams>, res: Response<{ ok: boolean }>) => {
+  await markRead(req.params.id);
+  res.json({ ok: true });
+});
+
+export default router;

package/server/api/routes/sessionsCursor.ts

@@ -0,0 +1,59 @@
+// Cursor logic for `GET /api/sessions?since=<cursor>` (issue #205).
+//
+// Kept separate from `sessions.ts` so the pure logic can be unit
+// tested without an Express harness.
+//
+// The cursor is deliberately opaque to the client: today it encodes
+// the max "change timestamp" (ms since epoch) as `"v1:<ms>"`, where a
+// session's change timestamp is `max(jsonlMtimeMs, indexedAtMs)`. We
+// prefix with `v1:` so a future encoding change (e.g. adding a
+// deletion generation counter for approach A when deletion lands)
+// can bump the prefix without clients caring — they always echo back
+// whatever the server handed them.
+
+const CURSOR_PREFIX = "v1:";
+
+/**
+ * Encode a change timestamp (ms) as an opaque cursor string.
+ *
+ * `changeMs <= 0` is allowed and yields `"v1:0"` — that's the
+ * "beginning of time" cursor a client will never hold but which we
+ * fall back to when an incoming cursor is malformed.
+ */
+export function encodeCursor(changeMs: number): string {
+  const ms = Number.isFinite(changeMs) && changeMs > 0 ? Math.floor(changeMs) : 0;
+  return `${CURSOR_PREFIX}${ms}`;
+}
+
+/**
+ * Parse an incoming `?since=` cursor back to the ms timestamp it
+ * encodes. Anything the client sends that we don't recognise — old
+ * format, truncated, typo, empty — returns 0 so the client gets a
+ * full resend instead of a broken sidebar. This is intentionally
+ * forgiving; the failure mode is "downloads slightly more than
+ * needed once" which is the behaviour clients had pre-#205 anyway.
+ */
+export function parseCursor(raw: unknown): number {
+  if (typeof raw !== "string") return 0;
+  if (!raw.startsWith(CURSOR_PREFIX)) return 0;
+  const n = Number(raw.slice(CURSOR_PREFIX.length));
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Compute the per-session "change timestamp" in ms — the latest of:
+ *   - jsonl mtime (new user/assistant turn)
+ *   - chat-index `indexedAt` (AI-generated title / summary, updated in
+ *     the background and doesn't touch the jsonl)
+ *   - meta json mtime (hasUnread flip, origin update — also sidecar
+ *     to the jsonl)
+ *
+ * Missing / malformed `indexedAt` or `metaMtimeMs` contributes 0 so
+ * they don't pull the timestamp backward.
+ */
+export function sessionChangeMs(jsonlMtimeMs: number, indexedAtIso: string | undefined, metaMtimeMs: number | undefined = undefined): number {
+  const indexedAtMs = indexedAtIso !== undefined ? new Date(indexedAtIso).getTime() : NaN;
+  const safeIndexed = Number.isFinite(indexedAtMs) ? indexedAtMs : 0;
+  const safeMeta = typeof metaMtimeMs === "number" && Number.isFinite(metaMtimeMs) ? metaMtimeMs : 0;
+  return Math.max(jsonlMtimeMs, safeIndexed, safeMeta);
+}

package/server/api/routes/skills.ts

@@ -0,0 +1,195 @@
+// REST surface for Claude Code skills.
+//
+//   GET    /api/skills        → { skills: SkillSummary[] }                phase 0
+//   GET    /api/skills/:name  → { skill: Skill } | 404                    phase 0
+//   POST   /api/skills        → { saved: true, path } | 400/409          phase 1
+//   PUT    /api/skills/:name  → { updated: true, path } | 400/403/404    phase 2
+//   DELETE /api/skills/:name  → { deleted: true } | 400/403/404          phase 1
+//
+// Discovery reads both ~/.claude/skills/ (user) and
+// <workspace>/.claude/skills/ (project); project wins on name
+// collision. Writes are confined to the project scope —
+// `saveProjectSkill` / `updateProjectSkill` / `deleteProjectSkill`
+// enforce that.
+
+import { Router, Request, Response } from "express";
+import { deleteProjectSkill, discoverSkills, saveProjectSkill, updateProjectSkill } from "../../workspace/skills/index.js";
+import type { Skill, SkillSummary } from "../../workspace/skills/index.js";
+import { workspacePath } from "../../workspace/workspace.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { log } from "../../system/logger/index.js";
+import { refreshScheduledSkills } from "../../workspace/skills/scheduler.js";
+import { logBackgroundError } from "../../utils/logBackgroundError.js";
+import { badRequest, conflict, forbidden, notFound } from "../../utils/httpError.js";
+
+const router = Router();
+
+interface SkillsListResponse {
+  skills: SkillSummary[];
+}
+
+interface SkillDetailResponse {
+  skill: Skill;
+}
+
+interface ErrorResponse {
+  error: string;
+}
+
+interface SaveSkillBody {
+  name?: unknown;
+  description?: unknown;
+  body?: unknown;
+}
+
+interface SaveSkillResponse {
+  saved: true;
+  path: string;
+}
+
+interface DeleteSkillResponse {
+  deleted: true;
+  name: string;
+}
+
+router.get(API_ROUTES.skills.list, async (_req: Request, res: Response<SkillsListResponse>) => {
+  const skills = await discoverSkills({ workspaceRoot: workspacePath });
+  res.json({
+    skills: skills.map((s) => ({
+      name: s.name,
+      description: s.description,
+      source: s.source,
+    })),
+  });
+});
+
+router.get(API_ROUTES.skills.detail, async (req: Request<{ name: string }>, res: Response<SkillDetailResponse | ErrorResponse>) => {
+  const skills = await discoverSkills({ workspaceRoot: workspacePath });
+  const skill = skills.find((s) => s.name === req.params.name);
+  if (!skill) {
+    notFound(res, `skill not found: ${req.params.name}`);
+    return;
+  }
+  res.json({ skill });
+});
+
+router.post(API_ROUTES.skills.create, async (req: Request<object, unknown, SaveSkillBody>, res: Response<SaveSkillResponse | ErrorResponse>) => {
+  const { name, description, body } = req.body ?? {};
+  if (typeof name !== "string") {
+    badRequest(res, "name must be a string");
+    return;
+  }
+  if (typeof description !== "string") {
+    badRequest(res, "description must be a string");
+    return;
+  }
+  if (typeof body !== "string") {
+    badRequest(res, "body must be a string");
+    return;
+  }
+  const result = await saveProjectSkill({
+    workspaceRoot: workspacePath,
+    name,
+    description,
+    body,
+  });
+  if (result.kind === "saved") {
+    log.info("skills", "saved", { name });
+    refreshScheduledSkills().catch(logBackgroundError("skills"));
+    res.json({ saved: true, path: result.path });
+    return;
+  }
+  if (result.kind === "invalid-slug") {
+    badRequest(
+      res,
+      `invalid slug: "${result.slug}". Use lowercase letters, digits, and hyphens (1-64 chars, no leading/trailing hyphen, no consecutive hyphens).`,
+    );
+    return;
+  }
+  if (result.kind === "missing-field") {
+    badRequest(res, `${result.field} must be a non-empty string`);
+    return;
+  }
+  if (result.kind === "exists") {
+    conflict(res, `skill already exists: ${result.name}. Choose a different name or delete the existing one first.`);
+  }
+});
+
+interface UpdateSkillBody {
+  description?: unknown;
+  body?: unknown;
+}
+
+interface UpdateSkillResponse {
+  updated: true;
+  path: string;
+}
+
+router.put(API_ROUTES.skills.update, async (req: Request<{ name: string }, unknown, UpdateSkillBody>, res: Response<UpdateSkillResponse | ErrorResponse>) => {
+  const { name } = req.params;
+  const { description, body } = req.body ?? {};
+  if (typeof description !== "string") {
+    badRequest(res, "description must be a string");
+    return;
+  }
+  if (typeof body !== "string") {
+    badRequest(res, "body must be a string");
+    return;
+  }
+  const result = await updateProjectSkill({
+    workspaceRoot: workspacePath,
+    name,
+    description,
+    body,
+  });
+  if (result.kind === "updated") {
+    log.info("skills", "updated", { name });
+    refreshScheduledSkills().catch(logBackgroundError("skills"));
+    res.json({ updated: true, path: result.path });
+    return;
+  }
+  if (result.kind === "invalid-slug") {
+    badRequest(res, `invalid slug: "${result.slug}"`);
+    return;
+  }
+  if (result.kind === "missing-field") {
+    badRequest(res, `${result.field} must be a non-empty string`);
+    return;
+  }
+  if (result.kind === "user-scope") {
+    forbidden(res, `cannot update user-scope skill "${result.name}" — only project-scope skills are writable.`);
+    return;
+  }
+  if (result.kind === "not-found") {
+    notFound(res, `skill not found: ${result.name}`);
+  }
+});
+
+router.delete(API_ROUTES.skills.remove, async (req: Request<{ name: string }>, res: Response<DeleteSkillResponse | ErrorResponse>) => {
+  const result = await deleteProjectSkill({
+    workspaceRoot: workspacePath,
+    name: req.params.name,
+  });
+  if (result.kind === "deleted") {
+    log.info("skills", "deleted", { name: result.name });
+    refreshScheduledSkills().catch(logBackgroundError("skills"));
+    res.json({ deleted: true, name: result.name });
+    return;
+  }
+  if (result.kind === "invalid-slug") {
+    badRequest(res, `invalid slug: "${result.slug}"`);
+    return;
+  }
+  if (result.kind === "user-scope") {
+    forbidden(
+      res,
+      `cannot delete user-scope skill "${result.name}" — only project-scope skills under ~/mulmoclaude/.claude/skills/ are writable from MulmoClaude.`,
+    );
+    return;
+  }
+  if (result.kind === "not-found") {
+    notFound(res, `skill not found: ${result.name}`);
+  }
+});
+
+export default router;