mulmoclaude 0.1.0

package/server/utils/files/scheduler-overrides-io.ts

@@ -0,0 +1,64 @@
+// Domain I/O for scheduler override config.
+//
+// Reads/writes config/scheduler/overrides.json. Each key is a
+// system task ID (e.g. "system:journal"), value overrides the
+// default schedule.
+
+import fs from "fs";
+import path from "path";
+import { workspacePath } from "../../workspace/paths.js";
+import { WORKSPACE_FILES } from "../../../src/config/workspacePaths.js";
+import { loadJsonFile } from "./json.js";
+import { writeFileAtomicSync } from "./atomic.js";
+import { log } from "../../system/logger/index.js";
+import { isRecord } from "../types.js";
+
+export interface ScheduleOverride {
+  /** Override interval in milliseconds (for interval-type schedules). */
+  intervalMs?: number;
+  /** Override time "HH:MM" in UTC (for daily-type schedules). */
+  time?: string;
+}
+
+export type ScheduleOverrides = Record<string, ScheduleOverride>;
+
+/** Strict HH:MM validation — rejects 99:99 etc. */
+export const UTC_HH_MM_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+function isScheduleOverride(value: unknown): value is ScheduleOverride {
+  if (!isRecord(value)) return false;
+  const obj = value;
+  const hasInterval = "intervalMs" in obj && typeof obj.intervalMs === "number" && obj.intervalMs > 0;
+  const hasTime = "time" in obj && typeof obj.time === "string" && UTC_HH_MM_RE.test(obj.time);
+  // At least one valid field required
+  return hasInterval || hasTime;
+}
+
+function overridesPath(root?: string): string {
+  return path.join(root ?? workspacePath, WORKSPACE_FILES.schedulerOverrides);
+}
+
+/** Load schedule overrides. Filters out invalid entries with a warning. */
+export function loadSchedulerOverrides(root?: string): ScheduleOverrides {
+  const raw = loadJsonFile<unknown>(overridesPath(root), {});
+  if (!isRecord(raw)) {
+    log.warn("scheduler-overrides", "overrides.json is not an object");
+    return {};
+  }
+  const result: ScheduleOverrides = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (isScheduleOverride(value)) {
+      result[key] = value;
+    } else {
+      log.warn("scheduler-overrides", "invalid entry, skipping", { key });
+    }
+  }
+  return result;
+}
+
+/** Save schedule overrides atomically. Creates directory if needed. */
+export function saveSchedulerOverrides(overrides: ScheduleOverrides, root?: string): void {
+  const filePath = overridesPath(root);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileAtomicSync(filePath, JSON.stringify(overrides, null, 2));
+}

package/server/utils/files/session-io.ts

@@ -0,0 +1,136 @@
+// Domain I/O: chat sessions
+//   conversations/chat/<id>.json   — metadata
+//   conversations/chat/<id>.jsonl  — event log
+//
+// All functions take optional `root` for test DI.
+
+import { appendFile } from "fs/promises";
+import path from "node:path";
+import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+import { workspacePath } from "../../workspace/paths.js";
+import { readTextUnder, writeTextUnder, resolvePath, ensureWorkspaceDir } from "./workspace-io.js";
+
+const CHAT = WORKSPACE_DIRS.chat;
+const root = (rootOverride?: string) => rootOverride ?? workspacePath;
+
+/** Ensure the chat directory exists. Called once at session start. */
+export function ensureChatDir(): void {
+  ensureWorkspaceDir(CHAT);
+}
+
+function metaRel(id: string): string {
+  return path.posix.join(CHAT, `${id}.json`);
+}
+
+function jsonlRel(id: string): string {
+  return path.posix.join(CHAT, `${id}.jsonl`);
+}
+
+// ── Meta ────────────────────────────────────────────────────────
+
+export interface SessionMeta {
+  roleId?: string;
+  startedAt?: string;
+  firstUserMessage?: string;
+  claudeSessionId?: string;
+  hasUnread?: boolean;
+  origin?: "human" | "scheduler" | "skill" | "bridge";
+  [key: string]: unknown;
+}
+
+export type ReadMetaResult = { kind: "missing" } | { kind: "ok"; meta: SessionMeta } | { kind: "corrupt"; raw: string };
+
+/** Read session metadata with full outcome discrimination. */
+export async function readSessionMetaFull(id: string, rootOverride?: string): Promise<ReadMetaResult> {
+  const raw = await readTextUnder(root(rootOverride), metaRel(id));
+  if (raw === null) return { kind: "missing" };
+  try {
+    return { kind: "ok", meta: JSON.parse(raw) as SessionMeta };
+  } catch {
+    return { kind: "corrupt", raw };
+  }
+}
+
+/** Convenience: returns the meta or null. Treats corrupt as null
+ *  (callers that need to distinguish use readSessionMetaFull). */
+export async function readSessionMeta(id: string, rootOverride?: string): Promise<SessionMeta | null> {
+  const result = await readSessionMetaFull(id, rootOverride);
+  return result.kind === "ok" ? result.meta : null;
+}
+
+export async function writeSessionMeta(id: string, meta: SessionMeta, rootOverride?: string): Promise<void> {
+  await writeTextUnder(root(rootOverride), metaRel(id), JSON.stringify(meta, null, 2));
+}
+
+export async function createSessionMeta(id: string, roleId: string, firstUserMessage: string, rootOverride?: string, origin?: string): Promise<void> {
+  const meta: Record<string, unknown> = {
+    roleId,
+    startedAt: new Date().toISOString(),
+    firstUserMessage,
+  };
+  if (origin) meta.origin = origin;
+  await writeSessionMeta(id, meta, rootOverride);
+}
+
+export async function backfillOrigin(id: string, origin: SessionMeta["origin"], rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(id, rootOverride);
+  if (!meta || meta.origin) return; // already set
+  await writeSessionMeta(id, { ...meta, origin }, rootOverride);
+}
+
+export async function backfillFirstUserMessage(id: string, message: string, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(id, rootOverride);
+  if (!meta || meta.firstUserMessage) return;
+  await writeSessionMeta(id, { ...meta, firstUserMessage: message }, rootOverride);
+}
+
+export async function setClaudeSessionId(id: string, claudeSessionId: string, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(id, rootOverride);
+  if (!meta) return;
+  await writeSessionMeta(id, { ...meta, claudeSessionId }, rootOverride);
+}
+
+export async function clearClaudeSessionId(id: string, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(id, rootOverride);
+  if (!meta) return;
+  const { claudeSessionId: __removed, ...rest } = meta;
+  await writeSessionMeta(id, rest, rootOverride);
+}
+
+export async function updateHasUnread(id: string, hasUnread: boolean, rootOverride?: string): Promise<void> {
+  const meta = await readSessionMeta(id, rootOverride);
+  if (!meta) return;
+  await writeSessionMeta(id, { ...meta, hasUnread }, rootOverride);
+}
+
+// ── Jsonl ───────────────────────────────────────────────────────
+
+export function sessionJsonlAbsPath(id: string, rootOverride?: string): string {
+  return resolvePath(root(rootOverride), jsonlRel(id));
+}
+
+/**
+ * Resolve the absolute path of a session's metadata JSON file. The
+ * jsonl variant is the event log; this one is the sidecar that holds
+ * `hasUnread`, `roleId`, `startedAt`, `origin`, etc. Its mtime bumps
+ * whenever any of those fields change via `writeSessionMeta`.
+ */
+export function sessionMetaAbsPath(id: string, rootOverride?: string): string {
+  return resolvePath(root(rootOverride), metaRel(id));
+}
+
+export async function readSessionJsonl(id: string, rootOverride?: string): Promise<string | null> {
+  return readTextUnder(root(rootOverride), jsonlRel(id));
+}
+
+/**
+ * Append a single line to the session event log (JSONL format).
+ *
+ * The function **ensures a trailing `\n`** — callers pass the raw
+ * content and don't need to worry about line termination. This
+ * prevents JSONL parse failures from missing newlines.
+ */
+export async function appendSessionLine(id: string, line: string, rootOverride?: string): Promise<void> {
+  const normalized = line.endsWith("\n") ? line : `${line}\n`;
+  await appendFile(resolvePath(root(rootOverride), jsonlRel(id)), normalized);
+}

package/server/utils/files/spreadsheet-store.ts

@@ -0,0 +1,63 @@
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
+import { resolveWithinRoot } from "./safe.js";
+
+const SPREADSHEETS_DIR = WORKSPACE_PATHS.spreadsheets;
+
+// Cached realpath of the spreadsheets directory. resolveWithinRoot
+// requires its root argument to be a realpath so symlinks are handled
+// correctly. Matches the pattern used in image-store.ts.
+let spreadsheetsDirReal: string | null = null;
+
+async function ensureSpreadsheetsDir(): Promise<string> {
+  if (spreadsheetsDirReal) return spreadsheetsDirReal;
+  await fs.mkdir(SPREADSHEETS_DIR, { recursive: true });
+  spreadsheetsDirReal = await fs.realpath(SPREADSHEETS_DIR);
+  return spreadsheetsDirReal;
+}
+
+// Resolve a workspace-relative spreadsheet path (e.g. "spreadsheets/abc.json")
+// into an absolute path guaranteed to be inside the spreadsheets directory.
+// Throws on traversal attempts.
+async function safeResolve(relativePath: string): Promise<string> {
+  const root = await ensureSpreadsheetsDir();
+  // Strip the leading "spreadsheets/" prefix so callers can pass either
+  // the stored form or just the filename.
+  const name = relativePath.replace(new RegExp(`^${WORKSPACE_DIRS.spreadsheets}/`), "");
+  const result = resolveWithinRoot(root, name);
+  if (!result) {
+    throw new Error(`path traversal rejected: ${relativePath}`);
+  }
+  return result;
+}
+
+/** Save sheets array as a JSON file. Returns the workspace-relative path. */
+export async function saveSpreadsheet(sheets: unknown[]): Promise<string> {
+  await ensureSpreadsheetsDir();
+  const id = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+  const filename = `${id}.json`;
+  await fs.writeFile(path.join(SPREADSHEETS_DIR, filename), JSON.stringify(sheets), "utf-8");
+  return path.posix.join(WORKSPACE_DIRS.spreadsheets, filename);
+}
+
+/** Overwrite an existing spreadsheet file. */
+export async function overwriteSpreadsheet(relativePath: string, sheets: unknown[]): Promise<void> {
+  const absPath = await safeResolve(relativePath);
+  await fs.writeFile(absPath, JSON.stringify(sheets), "utf-8");
+}
+
+/** Check if a string is a spreadsheet file path (not inline data).
+ *  Rejects traversal attempts like "spreadsheets/../outside.json"
+ *  so the caller can't rely on the prefix/suffix alone. */
+export function isSpreadsheetPath(value: string): boolean {
+  if (!value.startsWith(`${WORKSPACE_DIRS.spreadsheets}/`)) return false;
+  if (!value.endsWith(".json")) return false;
+  // Forbid .. segments anywhere in the path — a realpath check still
+  // happens server-side, but this catches obvious cases early.
+  const normalized = path.posix.normalize(value);
+  if (normalized !== value) return false;
+  if (normalized.includes("..")) return false;
+  return true;
+}

package/server/utils/files/todos-io.ts

@@ -0,0 +1,29 @@
+// Domain I/O: todo items + status columns
+//   data/todos/todos.json     — items
+//   data/todos/columns.json   — status columns
+//
+// Sync API. Optional `root` for test DI.
+
+import { WORKSPACE_FILES } from "../../workspace/paths.js";
+import { workspacePath } from "../../workspace/paths.js";
+import { resolvePath } from "./workspace-io.js";
+import { loadJsonFile } from "./json.js";
+import { writeFileAtomicSync } from "./atomic.js";
+
+const root = (r?: string) => r ?? workspacePath;
+
+export function loadTodos<T>(fallback: T, r?: string): T {
+  return loadJsonFile(resolvePath(root(r), WORKSPACE_FILES.todosItems), fallback);
+}
+
+export function saveTodos(items: unknown, r?: string): void {
+  writeFileAtomicSync(resolvePath(root(r), WORKSPACE_FILES.todosItems), JSON.stringify(items, null, 2));
+}
+
+export function loadColumns<T>(fallback: T, r?: string): T {
+  return loadJsonFile(resolvePath(root(r), WORKSPACE_FILES.todosColumns), fallback);
+}
+
+export function saveColumns(columns: unknown, r?: string): void {
+  writeFileAtomicSync(resolvePath(root(r), WORKSPACE_FILES.todosColumns), JSON.stringify(columns, null, 2));
+}

package/server/utils/files/user-tasks-io.ts

@@ -0,0 +1,25 @@
+// Domain I/O: user-created scheduled tasks
+//   config/scheduler/tasks.json
+//
+// Optional `root` parameter for test DI (defaults to workspacePath).
+
+import path from "path";
+import { mkdir } from "fs/promises";
+import { WORKSPACE_FILES } from "../../workspace/paths.js";
+import { workspacePath } from "../../workspace/paths.js";
+import { resolvePath } from "./workspace-io.js";
+import { loadJsonFile } from "./json.js";
+import { writeFileAtomic } from "./atomic.js";
+
+const root = (r?: string) => r ?? workspacePath;
+
+export function loadUserTasks<T>(r?: string): T[] {
+  const tasks = loadJsonFile<T[]>(resolvePath(root(r), WORKSPACE_FILES.schedulerUserTasks), []);
+  return Array.isArray(tasks) ? tasks : [];
+}
+
+export async function saveUserTasks<T>(tasks: T[], r?: string): Promise<void> {
+  const filePath = resolvePath(root(r), WORKSPACE_FILES.schedulerUserTasks);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFileAtomic(filePath, JSON.stringify(tasks, null, 2));
+}

package/server/utils/files/workspace-io.ts

@@ -0,0 +1,221 @@
+// Workspace-aware file I/O — the single place implementation code
+// should reach for when reading/writing files under ~/mulmoclaude/.
+//
+// Combines WORKSPACE_PATHS (path resolution) with the atomic/safe
+// helpers (I/O primitives) so call sites never need raw `path.join`
+// + raw `fs.*` for workspace files.
+//
+// All writes go through writeFileAtomic so concurrent readers always
+// see a consistent file — never a half-written one.
+//
+// All reads swallow ENOENT and return null / fallback so callers can
+// do `if (!content)` instead of try/catch.
+
+import fs from "fs";
+import path from "path";
+import { workspacePath } from "../../workspace/paths.js";
+import { writeFileAtomic, writeFileAtomicSync } from "./atomic.js";
+import { log } from "../../system/logger/index.js";
+import { isEnoent } from "./safe.js";
+
+function rethrowUnexpected(err: unknown, context: string): null {
+  if (isEnoent(err)) return null;
+  log.error("workspace-io", context, { error: String(err) });
+  throw err;
+}
+
+// ── Path resolution ─────────────────────────────────────────────
+
+/**
+ * Resolve a workspace-relative path to an absolute path.
+ * Use this instead of `path.join(workspacePath, rel)` in
+ * implementation code — keeps the workspace root reference in
+ * one place.
+ */
+export function resolveWorkspacePath(relPath: string): string {
+  return path.join(workspacePath, relPath);
+}
+
+// ── Read ────────────────────────────────────────────────────────
+
+/**
+ * Read a text file under the workspace. Returns null on ENOENT;
+ * logs and re-throws unexpected errors (EACCES, EPERM, etc.).
+ */
+export async function readWorkspaceText(relPath: string): Promise<string | null> {
+  try {
+    return await fs.promises.readFile(resolveWorkspacePath(relPath), "utf-8");
+  } catch (err) {
+    return rethrowUnexpected(err, `readWorkspaceText(${relPath})`);
+  }
+}
+
+/** Sync variant. Same ENOENT-only swallow contract. */
+export function readWorkspaceTextSync(relPath: string): string | null {
+  try {
+    return fs.readFileSync(resolveWorkspacePath(relPath), "utf-8");
+  } catch (err) {
+    return rethrowUnexpected(err, `readWorkspaceTextSync(${relPath})`);
+  }
+}
+
+/**
+ * Read and parse a JSON file under the workspace. Returns
+ * `fallback` if the file is missing, unreadable, or malformed.
+ */
+export async function readWorkspaceJson<T>(relPath: string, fallback: T): Promise<T> {
+  const text = await readWorkspaceText(relPath);
+  if (text === null) return fallback;
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/** Sync variant of `readWorkspaceJson`. */
+export function readWorkspaceJsonSync<T>(relPath: string, fallback: T): T {
+  const text = readWorkspaceTextSync(relPath);
+  if (text === null) return fallback;
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+// ── Write ───────────────────────────────────────────────────────
+
+/**
+ * Write a text file under the workspace atomically.
+ * Parent directories are created if missing.
+ */
+export async function writeWorkspaceText(relPath: string, content: string, opts?: { mode?: number }): Promise<void> {
+  await writeFileAtomic(resolveWorkspacePath(relPath), content, opts);
+}
+
+/** Sync variant for startup / init paths. */
+export function writeWorkspaceTextSync(relPath: string, content: string, opts?: { mode?: number }): void {
+  writeFileAtomicSync(resolveWorkspacePath(relPath), content, opts);
+}
+
+/**
+ * Write a JSON value under the workspace atomically.
+ * Pretty-printed with 2-space indent.
+ */
+export async function writeWorkspaceJson(relPath: string, data: unknown, opts?: { mode?: number }): Promise<void> {
+  await writeFileAtomic(resolveWorkspacePath(relPath), JSON.stringify(data, null, 2), opts);
+}
+
+// ── Rooted variants (for DI / testable modules) ────────────────
+//
+// Modules that take `root` as a parameter (journal, sources, etc.)
+// use these instead of raw path.join + fs.*. Same contract as the
+// workspace-* helpers, but root is caller-supplied.
+//
+// **IMPORTANT — internal paths only.** These helpers do NOT guard
+// against `..` traversal. They are designed for domain I/O modules
+// that pass compile-time-fixed relative paths like
+// `${WORKSPACE_DIRS.chat}/${id}.json`. User-supplied or HTTP-body
+// paths MUST go through `resolveWithinRoot()` in `safe.ts` instead.
+
+/**
+ * Resolve root + relPath. Replaces raw `path.join(root, rel)`.
+ *
+ * For **internal fixed paths only** — never pass user input as
+ * `relPath`. Use `resolveWithinRoot()` for user-supplied paths.
+ */
+export function resolvePath(root: string, relPath: string): string {
+  return path.join(root, relPath);
+}
+
+/** Read text under an arbitrary root. Null on ENOENT; rethrows
+ *  unexpected errors. */
+export async function readTextUnder(root: string, relPath: string): Promise<string | null> {
+  try {
+    return await fs.promises.readFile(path.join(root, relPath), "utf-8");
+  } catch (err) {
+    return rethrowUnexpected(err, `readTextUnder(${relPath})`);
+  }
+}
+
+/** Write atomically under an arbitrary root. */
+export async function writeTextUnder(root: string, relPath: string, content: string): Promise<void> {
+  await writeFileAtomic(path.join(root, relPath), content);
+}
+
+/** Sync read text under a root. Null on ENOENT. */
+export function readTextUnderSync(root: string, relPath: string): string | null {
+  try {
+    return fs.readFileSync(path.join(root, relPath), "utf-8");
+  } catch (err) {
+    return rethrowUnexpected(err, `readTextUnderSync(${relPath})`);
+  }
+}
+
+/** Sync readdir under a root. Empty on ENOENT. */
+export function readdirUnderSync(root: string, relPath: string): string[] {
+  try {
+    return fs.readdirSync(path.join(root, relPath));
+  } catch (err) {
+    if (isEnoent(err)) return [];
+    log.error("workspace-io", `readdirUnderSync(${relPath})`, {
+      error: String(err),
+    });
+    throw err;
+  }
+}
+
+/** Readdir under a root. Empty on ENOENT; rethrows unexpected. */
+export async function readdirUnder(root: string, relPath: string): Promise<string[]> {
+  try {
+    return await fs.promises.readdir(path.join(root, relPath));
+  } catch (err) {
+    if (isEnoent(err)) return [];
+    log.error("workspace-io", `readdirUnder(${relPath})`, {
+      error: String(err),
+    });
+    throw err;
+  }
+}
+
+/** Stat under a root. Null on ENOENT; rethrows unexpected. */
+export async function statUnder(root: string, relPath: string): Promise<fs.Stats | null> {
+  try {
+    return await fs.promises.stat(path.join(root, relPath));
+  } catch (err) {
+    return rethrowUnexpected(err, `statUnder(${relPath})`);
+  }
+}
+
+/** Ensure a directory exists under a root. */
+export async function ensureDirUnder(root: string, relPath: string): Promise<void> {
+  await fs.promises.mkdir(path.join(root, relPath), { recursive: true });
+}
+
+// ── Existence ───────────────────────────────────────────────────
+
+/**
+ * Check whether a workspace-relative path exists on disk.
+ * Returns false on ENOENT; rethrows unexpected errors.
+ */
+export function existsInWorkspace(relPath: string): boolean {
+  try {
+    fs.statSync(resolveWorkspacePath(relPath));
+    return true;
+  } catch (err) {
+    if (isEnoent(err)) return false;
+    log.error("workspace-io", `existsInWorkspace(${relPath})`, {
+      error: String(err),
+    });
+    throw err;
+  }
+}
+
+/**
+ * Ensure a workspace-relative directory exists. Creates it
+ * (including parents) if missing. Idempotent.
+ */
+export function ensureWorkspaceDir(relPath: string): void {
+  fs.mkdirSync(resolveWorkspacePath(relPath), { recursive: true });
+}

package/server/utils/gemini.ts

@@ -0,0 +1,59 @@
+import { GoogleGenAI, type GenerateContentParameters } from "@google/genai";
+import { env } from "../system/env.js";
+
+export { isGeminiAvailable } from "../system/env.js";
+
+export function getGeminiClient(): GoogleGenAI {
+  const apiKey = env.geminiApiKey;
+  if (!apiKey) throw new Error("GEMINI_API_KEY is not set");
+  return new GoogleGenAI({ apiKey });
+}
+
+// --- Image generation -----------------------------------------------
+
+const DEFAULT_IMAGE_MODEL = "gemini-3.1-flash-image-preview";
+
+const DEFAULT_IMAGE_CONFIG: GenerateContentParameters["config"] = {
+  responseModalities: ["TEXT", "IMAGE"],
+  imageConfig: { aspectRatio: "16:9" },
+};
+
+export interface GeminiImageResult {
+  // Raw base64 payload (no `data:` prefix). Undefined if Gemini
+  // declined to return an image, e.g. because the prompt was filtered.
+  imageData?: string;
+  // Optional text part returned alongside the image (or in lieu of
+  // it). Used as a fallback message when imageData is empty.
+  message?: string;
+}
+
+// Low-level wrapper around `ai.models.generateContent` that pulls
+// the first inline image and text part out of the response. Use this
+// when you need to pass custom `contents` (e.g. text + reference
+// image for /edit-image). Pass `undefined` for `config` to omit it
+// entirely from the request.
+export async function generateGeminiImageContent(
+  contents: GenerateContentParameters["contents"],
+  config?: GenerateContentParameters["config"],
+  model: string = DEFAULT_IMAGE_MODEL,
+): Promise<GeminiImageResult> {
+  const ai = getGeminiClient();
+  const response = await ai.models.generateContent({
+    model,
+    contents,
+    ...(config && { config }),
+  });
+  const parts = response.candidates?.[0]?.content?.parts ?? [];
+  const result: GeminiImageResult = {};
+  for (const part of parts) {
+    if (part.text) result.message = part.text;
+    if (part.inlineData?.data) result.imageData = part.inlineData.data;
+  }
+  return result;
+}
+
+// Convenience wrapper for the common "text prompt → image" path.
+// Uses the standard 16:9 image config.
+export async function generateGeminiImageFromPrompt(prompt: string, model?: string): Promise<GeminiImageResult> {
+  return generateGeminiImageContent([{ text: prompt }], DEFAULT_IMAGE_CONFIG, model);
+}

package/server/utils/gitignore.ts

@@ -0,0 +1,69 @@
+// .gitignore-aware path filtering for the Files API (#256 P2).
+//
+// Reads `.gitignore` files at each directory level during the tree
+// walk and filters entries that match. Uses the `ignore` npm package
+// which implements the full gitignore spec (negation, glob, anchoring,
+// directory-only patterns, etc.).
+//
+// Design: the `GitignoreFilter` builds a chain of `ignore` instances
+// as the walker descends. Each directory may add its own `.gitignore`
+// rules on top of the parent's. The `ignores(relPath)` method tests
+// the full chain so parent rules apply to children.
+//
+// Performance: `.gitignore` files are read synchronously during the
+// walk (one readFileSync per directory that has a `.gitignore`). For
+// the workspace scale (~hundreds of dirs) this is negligible. If
+// profiling shows otherwise, cache the parsed ignore instances.
+
+import fs from "fs";
+import path from "path";
+import ignore, { type Ignore } from "ignore";
+
+export class GitignoreFilter {
+  private ig: Ignore;
+
+  constructor(rules?: string) {
+    this.ig = ignore();
+    if (rules) {
+      this.ig.add(rules);
+    }
+  }
+
+  /** Test whether a workspace-relative path should be hidden. */
+  ignores(relPath: string): boolean {
+    if (!relPath) return false;
+    return this.ig.ignores(relPath);
+  }
+
+  /** Create a child filter that inherits this filter's rules and
+   *  adds any `.gitignore` found in `dirAbsPath`. */
+  childForDir(dirAbsPath: string): GitignoreFilter {
+    const child = new GitignoreFilter();
+    // Inherit parent rules
+    child.ig = ignore().add(this.ig);
+    // Add local .gitignore if present
+    const gitignorePath = path.join(dirAbsPath, ".gitignore");
+    try {
+      const content = fs.readFileSync(gitignorePath, "utf-8");
+      child.ig.add(content);
+    } catch {
+      // No .gitignore in this directory — just inherit parent
+    }
+    return child;
+  }
+}
+
+/**
+ * Create a root filter from the workspace's `.gitignore`.
+ * Returns a filter that always returns false (ignores nothing) if
+ * no `.gitignore` exists at the workspace root.
+ */
+export function createRootFilter(workspaceRoot: string): GitignoreFilter {
+  const gitignorePath = path.join(workspaceRoot, ".gitignore");
+  try {
+    const content = fs.readFileSync(gitignorePath, "utf-8");
+    return new GitignoreFilter(content);
+  } catch {
+    return new GitignoreFilter();
+  }
+}

package/server/utils/http.ts

@@ -0,0 +1,15 @@
+// HTTP utility helpers shared across server code.
+
+/**
+ * Safely extract the response body text. Returns empty string
+ * on any error (network reset, invalid encoding, etc.).
+ * Replaces the repeated `.text().catch(() => "")` pattern.
+ */
+export async function safeResponseText(res: Response, maxLength = 200): Promise<string> {
+  try {
+    const text = await res.text();
+    return text.slice(0, maxLength);
+  } catch {
+    return "";
+  }
+}