mulmoclaude 0.3.0 → 0.5.0

package/server/api/routes/mulmo-script.ts

@@ -1,8 +1,9 @@
 import { Router, Request, Response } from "express";
-import fs from "fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "fs";
 import path from "path";
 import { WORKSPACE_PATHS } from "../../workspace/paths.js";
 import { stripDataUri } from "../../utils/files/image-store.js";
+import { writeJsonAtomic } from "../../utils/files/json.js";
 import {
   getFileObject,
   initializeContextFromFiles,
@@ -26,6 +27,7 @@ import { slugify } from "../../utils/slug.js";
 import { resolveWithinRoot } from "../../utils/files/safe.js";
 import { errorMessage } from "../../utils/errors.js";
 import { badRequest, notFound, serverError } from "../../utils/httpError.js";
+import { getOptionalStringQuery } from "../../utils/request.js";
 import { log } from "../../system/logger/index.js";
 import { validateUpdateBeatBody, validateUpdateScriptBody } from "./mulmoScriptValidate.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
@@ -54,8 +56,8 @@ let storiesRealCache: string | null = null;
 function ensureStoriesReal(): string | null {
   if (storiesRealCache) return storiesRealCache;
   try {
-    fs.mkdirSync(storiesDir, { recursive: true });
-    storiesRealCache = fs.realpathSync(storiesDir);
+    mkdirSync(storiesDir, { recursive: true });
+    storiesRealCache = realpathSync(storiesDir);
     return storiesRealCache;
   } catch {
     return null;
@@ -96,7 +98,7 @@ interface FilePathQuery {
   filePath?: string;
 }
 
-router.post(API_ROUTES.mulmoScript.save, (req: Request<object, object, SaveMulmoScriptBody>, res: Response) => {
+router.post(API_ROUTES.mulmoScript.save, async (req: Request<object, object, SaveMulmoScriptBody>, res: Response) => {
   const { script, filename } = req.body;
 
   if (!script || !Array.isArray(script.beats)) {
@@ -104,14 +106,14 @@ router.post(API_ROUTES.mulmoScript.save, (req: Request<object, object, SaveMulmo
     return;
   }
 
-  fs.mkdirSync(storiesDir, { recursive: true });
+  mkdirSync(storiesDir, { recursive: true });
 
   const title = script.title || "untitled";
   const slug = filename ? filename.replace(/\.json$/, "") : slugify(title);
   const fname = `${slug}-${Date.now()}.json`;
   const filePath = path.join(storiesDir, fname);
 
-  fs.writeFileSync(filePath, JSON.stringify(script, null, 2));
+  await writeJsonAtomic(filePath, script);
 
   res.json({
     data: { script, filePath: `stories/${fname}` },
@@ -120,7 +122,7 @@ router.post(API_ROUTES.mulmoScript.save, (req: Request<object, object, SaveMulmo
   });
 });
 
-router.post(API_ROUTES.mulmoScript.updateBeat, (req: Request<object, object, unknown>, res: Response) => {
+router.post(API_ROUTES.mulmoScript.updateBeat, async (req: Request<object, object, unknown>, res: Response) => {
   const validation = validateUpdateBeatBody(req.body);
   if (!validation.ok) {
     badRequest(res, validation.error);
@@ -131,7 +133,7 @@ router.post(API_ROUTES.mulmoScript.updateBeat, (req: Request<object, object, unk
   const absoluteFilePath = resolveStoryPath(filePath, res);
   if (!absoluteFilePath) return;
 
-  const script: MulmoScript = JSON.parse(fs.readFileSync(absoluteFilePath, "utf-8"));
+  const script: MulmoScript = JSON.parse(readFileSync(absoluteFilePath, "utf-8"));
 
   if (!Array.isArray(script.beats) || beatIndex >= script.beats.length) {
     badRequest(res, "Invalid beatIndex");
@@ -139,12 +141,12 @@ router.post(API_ROUTES.mulmoScript.updateBeat, (req: Request<object, object, unk
   }
 
   script.beats[beatIndex] = beat as MulmoBeat;
-  fs.writeFileSync(absoluteFilePath, JSON.stringify(script, null, 2));
+  await writeJsonAtomic(absoluteFilePath, script);
 
   res.json({ ok: true });
 });
 
-router.post(API_ROUTES.mulmoScript.updateScript, (req: Request<object, object, unknown>, res: Response) => {
+router.post(API_ROUTES.mulmoScript.updateScript, async (req: Request<object, object, unknown>, res: Response) => {
   const validation = validateUpdateScriptBody(req.body);
   if (!validation.ok) {
     badRequest(res, validation.error);
@@ -155,7 +157,7 @@ router.post(API_ROUTES.mulmoScript.updateScript, (req: Request<object, object, u
   const absoluteFilePath = resolveStoryPath(filePath, res);
   if (!absoluteFilePath) return;
 
-  fs.writeFileSync(absoluteFilePath, JSON.stringify(updatedScript, null, 2));
+  await writeJsonAtomic(absoluteFilePath, updatedScript);
   res.json({ ok: true });
 });
 
@@ -170,7 +172,7 @@ router.get(API_ROUTES.mulmoScript.beatImage, async (req: Request<object, BeatIma
 
   await withStoryContext(res, filePath, {}, async ({ context }) => {
     const { imagePath } = getBeatPngImagePath(context, beatIndex);
-    if (!fs.existsSync(imagePath)) {
+    if (!existsSync(imagePath)) {
       res.json({ image: null });
       return;
     }
@@ -197,13 +199,13 @@ router.get(API_ROUTES.mulmoScript.movieStatus, async (req: Request<object, Movie
     }
 
     const outputPath = movieFilePath(context);
-    if (!fs.existsSync(outputPath)) {
+    if (!existsSync(outputPath)) {
       res.json({ moviePath: null });
       return;
     }
 
-    const movieMtime = fs.statSync(outputPath).mtimeMs;
-    const sourceMtime = fs.statSync(absoluteFilePath).mtimeMs;
+    const movieMtime = statSync(outputPath).mtimeMs;
+    const sourceMtime = statSync(absoluteFilePath).mtimeMs;
     if (movieMtime < sourceMtime) {
       res.json({ moviePath: null });
       return;
@@ -216,7 +218,7 @@ router.get(API_ROUTES.mulmoScript.movieStatus, async (req: Request<object, Movie
 });
 
 function fileToDataUri(filePath: string, mimeType: string): string {
-  const data = fs.readFileSync(filePath);
+  const data = readFileSync(filePath);
   return `data:${mimeType};base64,${data.toString("base64")}`;
 }
 
@@ -257,7 +259,7 @@ function resolveStoryPath(filePath: string, res: Response): string | null {
   const resolved = resolveWithinRoot(storiesReal, relFromStories);
   if (!resolved) {
     const candidate = path.resolve(storiesReal, relFromStories);
-    if (!fs.existsSync(candidate)) {
+    if (!existsSync(candidate)) {
       notFound(res, `File not found: ${filePath}`);
     } else {
       badRequest(res, "Invalid filePath");
@@ -373,12 +375,12 @@ router.get(API_ROUTES.mulmoScript.beatAudio, async (req: Request<object, BeatAud
     filePath,
     {
       operation: "beat-audio",
-      onContextMissing: (r) => r.json({ audio: null }),
+      onContextMissing: (response) => response.json({ audio: null }),
     },
     async ({ context }) => {
       const beat = context.studio.script.beats[beatIndex];
       const audioPath = getBeatAudioPathOrUrl(beat.text ?? "", context, beat, context.lang);
-      if (!audioPath || !fs.existsSync(audioPath)) {
+      if (!audioPath || !existsSync(audioPath)) {
         res.json({ audio: null });
         return;
       }
@@ -422,7 +424,7 @@ router.post(
           const beat = context.studio.script.beats[beatIndex];
           const audioPath = context.studio.beats[beatIndex]?.audioFile ?? getBeatAudioPathOrUrl(beat.text ?? "", context, beat, context.lang);
 
-          if (!audioPath || !fs.existsSync(audioPath)) {
+          if (!audioPath || !existsSync(audioPath)) {
             // Logic-flow failure (not an exception) — emit a targeted
             // log. Don't write raw `beat.text` into persistent logs —
             // it's free-form user content and can contain sensitive
@@ -430,7 +432,7 @@ router.post(
             log.error("generate-beat-audio", "audio was not generated", {
               beatIndex,
               audioPath,
-              exists: audioPath ? fs.existsSync(audioPath) : false,
+              exists: audioPath ? existsSync(audioPath) : false,
               beatTextLength: typeof beat?.text === "string" ? beat.text.length : 0,
               audioFilePresent: Boolean(context.studio.beats[beatIndex]?.audioFile),
             });
@@ -475,7 +477,7 @@ router.post(API_ROUTES.mulmoScript.renderBeat, async (req: Request<object, objec
         });
 
         const { imagePath } = getBeatPngImagePath(context, beatIndex);
-        if (!fs.existsSync(imagePath)) {
+        if (!existsSync(imagePath)) {
           genError = "Image was not generated";
           serverError(res, genError);
           return;
@@ -542,7 +544,7 @@ router.post(API_ROUTES.mulmoScript.generateMovie, async (req: Request<object, ob
       await movie(audioContext);
 
       const outputPath = movieFilePath(audioContext);
-      if (!fs.existsSync(outputPath)) {
+      if (!existsSync(outputPath)) {
         genError = "Movie was not generated";
         send({ type: "error", message: genError });
         res.end();
@@ -594,7 +596,7 @@ router.get(
 
     await withStoryContext(res, filePath, {}, async ({ context }) => {
       const imagePath = getReferenceImagePath(context, key, "png");
-      if (!fs.existsSync(imagePath)) {
+      if (!existsSync(imagePath)) {
         res.json({ image: null });
         return;
       }
@@ -613,10 +615,10 @@ router.post(API_ROUTES.mulmoScript.uploadBeatImage, async (req: Request<object,
 
   await withStoryContext(res, filePath, {}, async ({ context }) => {
     const { imagePath } = getBeatPngImagePath(context, beatIndex);
-    fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+    mkdirSync(path.dirname(imagePath), { recursive: true });
 
     const base64 = stripDataUri(imageData);
-    fs.writeFileSync(imagePath, Buffer.from(base64, "base64"));
+    writeFileSync(imagePath, Buffer.from(base64, "base64"));
 
     res.json({ image: fileToDataUri(imagePath, "image/png") });
   });
@@ -647,7 +649,7 @@ router.post(
 
           const index = Object.keys(images).indexOf(key);
           const imagePath = getReferenceImagePath(context, key, "png");
-          fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+          mkdirSync(path.dirname(imagePath), { recursive: true });
 
           await generateReferenceImage({
             context,
@@ -656,7 +658,7 @@ router.post(
             image: imageEntry as MulmoImagePromptMedia,
             force,
           });
-          if (!fs.existsSync(imagePath)) {
+          if (!existsSync(imagePath)) {
             genError = "Character image was not generated";
             serverError(res, genError);
             return;
@@ -685,10 +687,10 @@ router.post(
 
     await withStoryContext(res, filePath, {}, async ({ context }) => {
       const imagePath = getReferenceImagePath(context, key, "png");
-      fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+      mkdirSync(path.dirname(imagePath), { recursive: true });
 
       const base64 = stripDataUri(imageData);
-      fs.writeFileSync(imagePath, Buffer.from(base64, "base64"));
+      writeFileSync(imagePath, Buffer.from(base64, "base64"));
 
       res.json({ image: fileToDataUri(imagePath, "image/png") });
     });
@@ -696,7 +698,7 @@ router.post(
 );
 
 router.get(API_ROUTES.mulmoScript.downloadMovie, (req: Request, res: Response) => {
-  const moviePath = typeof req.query.moviePath === "string" ? req.query.moviePath : undefined;
+  const moviePath = getOptionalStringQuery(req, "moviePath");
 
   if (!moviePath) {
     badRequest(res, "moviePath is required");

package/server/api/routes/news.ts

@@ -0,0 +1,146 @@
+// HTTP routes for the news viewer (#761).
+//
+//   GET /api/news/items?days=N        — recent items, sorted desc
+//   GET /api/news/items/:id/body      — body markdown from per-source archive
+//   GET /api/news/read-state          — { readIds: string[] }
+//   PUT /api/news/read-state          — { readIds: string[] }
+//
+// The reader walks daily JSON indexes on demand (see
+// `server/workspace/news/reader.ts`); no separate index is
+// maintained — see issue #761 for the design rationale (covers ~30
+// days, follow-up ticket for full history).
+
+import path from "node:path";
+import { Router, type Request, type Response } from "express";
+import { workspacePath } from "../../workspace/workspace.js";
+import { aggregateRecentItems, loadItemBody, type NewsItem } from "../../workspace/news/reader.js";
+import { loadJsonFile, writeJsonAtomic } from "../../utils/files/json.js";
+import { WORKSPACE_FILES } from "../../../src/config/workspacePaths.js";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { badRequest, serverError } from "../../utils/httpError.js";
+import { errorMessage } from "../../utils/errors.js";
+import { isRecord } from "../../utils/types.js";
+import { log } from "../../system/logger/index.js";
+
+// Window upper bound — keeps memory bounded if a caller passes
+// a comically large `days`. Daily JSON aggregation is O(days * items)
+// in the worst case.
+const MAX_DAYS = 90;
+const DEFAULT_DAYS = 30;
+
+// Cap the read-state list size. UUID-shaped ids are ~16 bytes each;
+// 10k of them is < 200 KB, fine. Beyond that we evict from the front
+// (oldest mark-as-read first) so the working set stays small.
+const MAX_READ_IDS = 10_000;
+
+interface ReadState {
+  readIds: string[];
+}
+
+const router = Router();
+
+// ── /api/news/items ─────────────────────────────────────────────
+
+router.get(API_ROUTES.news.items, async (req: Request, res: Response<{ items: NewsItem[] } | { error: string }>) => {
+  const days = parseDays(req.query.days);
+  if (days === null) {
+    badRequest(res, "invalid `days` query parameter");
+    return;
+  }
+  try {
+    const items = await aggregateRecentItems(workspacePath, days);
+    res.json({ items });
+  } catch (err) {
+    log.error("news", "aggregate failed", { error: errorMessage(err) });
+    serverError(res, "failed to load news items");
+  }
+});
+
+function parseDays(raw: unknown): number | null {
+  if (raw === undefined) return DEFAULT_DAYS;
+  const value = Number(Array.isArray(raw) ? raw[0] : raw);
+  if (!Number.isInteger(value) || value <= 0) return null;
+  return Math.min(value, MAX_DAYS);
+}
+
+// ── /api/news/items/:id/body ─────────────────────────────────────
+//
+// Body lookup needs the item's `sourceSlug` + `publishedAt` to
+// pick the right archive file. We re-aggregate on demand (cheap;
+// could be cached later if it shows up in a hot path). The
+// frontend has the metadata already, but routing it through query
+// params would let an attacker fabricate paths — so we resolve from
+// the trusted in-memory aggregate keyed by `id` here.
+
+router.get(API_ROUTES.news.itemBody, async (req: Request<{ id: string }>, res: Response<{ body: string | null } | { error: string }>) => {
+  const { id } = req.params;
+  if (!id) {
+    badRequest(res, "missing item id");
+    return;
+  }
+  try {
+    const items = await aggregateRecentItems(workspacePath, MAX_DAYS);
+    const match = items.find((entry) => entry.id === id);
+    if (!match) {
+      res.json({ body: null });
+      return;
+    }
+    const body = await loadItemBody(workspacePath, match.sourceSlug, match.url, match.publishedAt);
+    res.json({ body });
+  } catch (err) {
+    log.error("news", "body lookup failed", { error: errorMessage(err) });
+    serverError(res, "failed to load item body");
+  }
+});
+
+// ── /api/news/read-state ─────────────────────────────────────────
+
+const readStateAbsPath = (): string => path.join(workspacePath, WORKSPACE_FILES.newsReadState);
+
+router.get(API_ROUTES.news.readState, (_req: Request, res: Response<ReadState | { error: string }>) => {
+  try {
+    const data = loadJsonFile<ReadState>(readStateAbsPath(), { readIds: [] });
+    const sanitized = sanitizeReadState(data);
+    res.json(sanitized);
+  } catch (err) {
+    log.error("news", "read-state load failed", {
+      error: errorMessage(err),
+    });
+    serverError(res, "failed to load news read-state");
+  }
+});
+
+router.put(API_ROUTES.news.readState, async (req: Request, res: Response<ReadState | { error: string }>) => {
+  const body = req.body;
+  if (!isRecord(body) || !Array.isArray(body.readIds)) {
+    badRequest(res, "expected { readIds: string[] }");
+    return;
+  }
+  const sanitized = sanitizeReadState({ readIds: body.readIds });
+  try {
+    await writeJsonAtomic(readStateAbsPath(), sanitized);
+    res.json(sanitized);
+  } catch (err) {
+    log.error("news", "read-state save failed", {
+      error: errorMessage(err),
+    });
+    serverError(res, "failed to save news read-state");
+  }
+});
+
+// Drop non-string entries, dedupe, cap at MAX_READ_IDS (keeping the
+// most recent — i.e. tail end — of the list). Pure for testability.
+export function sanitizeReadState(input: { readIds: unknown[] }): ReadState {
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  for (const value of input.readIds) {
+    if (typeof value !== "string" || value.length === 0) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+    ordered.push(value);
+  }
+  if (ordered.length <= MAX_READ_IDS) return { readIds: ordered };
+  return { readIds: ordered.slice(ordered.length - MAX_READ_IDS) };
+}
+
+export default router;

package/server/api/routes/notifications.ts

@@ -2,15 +2,27 @@
 // simultaneously to every open Web tab (pub-sub) and every bridge
 // (chat-service `pushToBridge`). Stepping stone for the in-app
 // notification center (#144) and external-channel notifications
-// (#142); see plans/feat-notification-push-scaffold.md for the
+// (#142); see plans/done/feat-notification-push-scaffold.md for the
 // motivation and the production plan.
 //
-// Usage:
+// Usage (basic):
 //   curl -X POST http://localhost:3001/api/notifications/test \
 //     -H "Authorization: Bearer $(cat ~/mulmoclaude/.session-token)" \
 //     -H "Content-Type: application/json" \
 //     -d '{"message":"hello","delaySeconds":5}'
 //
+// Usage (with permalink action — #762):
+//   curl -X POST http://localhost:3001/api/notifications/test \
+//     -H "Authorization: Bearer $TOKEN" \
+//     -H "Content-Type: application/json" \
+//     -d '{"message":"Scheduled task fired","kind":"scheduler",
+//          "action":{"type":"navigate",
+//                    "target":{"view":"automations",
+//                              "taskId":"finance-daily-briefing"}}}'
+//
+// For a one-shot "fire one of every target kind" run,
+// scripts/dev/fire-sample-notifications.sh drives this endpoint.
+//
 // The route is exported as a factory so the host wiring can inject
 // the pub-sub publisher and the chat-service push handle without
 // this file pulling in either module directly.
@@ -19,12 +31,23 @@ import { Router, type Request, type Response } from "express";
 import { scheduleTestNotification, type NotificationDeps, type ScheduleNotificationOptions } from "../../events/notifications.js";
 import { log } from "../../system/logger/index.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import {
+  NOTIFICATION_ACTION_TYPES,
+  NOTIFICATION_KINDS,
+  NOTIFICATION_VIEWS,
+  type NotificationAction,
+  type NotificationKind,
+} from "../../../src/types/notification.js";
+import { isRecord } from "../../utils/types.js";
 
 interface TestRequestBody {
   message?: unknown;
+  body?: unknown;
   delaySeconds?: unknown;
   transportId?: unknown;
   chatId?: unknown;
+  kind?: unknown;
+  action?: unknown;
 }
 
 interface TestResponse {
@@ -32,11 +55,40 @@ interface TestResponse {
   delaySeconds: number;
 }
 
+const KIND_SET = new Set<string>(Object.values(NOTIFICATION_KINDS));
+const VIEW_SET = new Set<string>(Object.values(NOTIFICATION_VIEWS));
+
+function parseKind(value: unknown): NotificationKind | undefined {
+  if (typeof value !== "string") return undefined;
+  return KIND_SET.has(value) ? (value as NotificationKind) : undefined;
+}
+
+// Loose validator — dev-facing so we prefer "pass through what looks
+// right" over strict type guards. Only checks that `type` is one of
+// the two known literals and, for navigates, that `target.view` is a
+// known view. The target's other fields are forwarded verbatim so
+// adding new optional fields doesn't require editing this file.
+function parseAction(value: unknown): NotificationAction | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.type === NOTIFICATION_ACTION_TYPES.none) {
+    return { type: NOTIFICATION_ACTION_TYPES.none };
+  }
+  if (value.type !== NOTIFICATION_ACTION_TYPES.navigate) return undefined;
+  const target = value.target;
+  if (!isRecord(target) || typeof target.view !== "string" || !VIEW_SET.has(target.view)) {
+    return undefined;
+  }
+  return { type: NOTIFICATION_ACTION_TYPES.navigate, target: target as NotificationAction extends { target: infer T } ? T : never };
+}
+
 function parseBody(body: TestRequestBody): ScheduleNotificationOptions {
   const opts: ScheduleNotificationOptions = {};
   if (typeof body.message === "string" && body.message.length > 0) {
     opts.message = body.message;
   }
+  if (typeof body.body === "string" && body.body.length > 0) {
+    opts.body = body.body;
+  }
   if (typeof body.delaySeconds === "number") {
     opts.delaySeconds = body.delaySeconds;
   }
@@ -46,6 +98,10 @@ function parseBody(body: TestRequestBody): ScheduleNotificationOptions {
   if (typeof body.chatId === "string" && body.chatId.length > 0) {
     opts.chatId = body.chatId;
   }
+  const kind = parseKind(body.kind);
+  if (kind) opts.kind = kind;
+  const action = parseAction(body.action);
+  if (action) opts.action = action;
   return opts;
 }
 

package/server/api/routes/pdf.ts

@@ -1,4 +1,4 @@
-import fs from "fs";
+import { realpathSync } from "fs";
 import path from "path";
 import { Router, Request, Response } from "express";
 import { marked } from "marked";
@@ -56,7 +56,7 @@ const MIME_BY_EXT: Record<string, string> = {
 // Realpath of the workspace, resolved once at module load. Used to
 // validate that image paths resolved relative to markdowns/ stay
 // inside the workspace after symlink resolution.
-const workspaceReal = fs.realpathSync(resolveWorkspacePath(""));
+const workspaceReal = realpathSync(resolveWorkspacePath(""));
 
 /**
  * Inline local images as base64 data URIs so Puppeteer can render them.