elanous 0.2.5 → 0.2.7

package/src/nexus/api/consult-requests.ts

@@ -0,0 +1,117 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { sendOutbound } from '../../domains/outbound-alert.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { jsonResponse } from './json-response.js';
+
+export const CONSULT_REQUESTS_PATH = '/v1/consult-requests';
+
+interface ConsultRequest {
+  receiptId: string;
+  name: string;
+  org: string | null;
+  kind: 'company' | 'personal';
+  interest: 'A' | 'B';
+  contact: string;
+  consent: true;
+  receivedAt: string;
+}
+
+export interface ConsultRequestsDeps {
+  root?: () => string;
+  now?: () => string;
+  send?: typeof sendOutbound;
+}
+
+function file(root: string): string {
+  return join(root, 'consult-requests', 'requests.jsonl');
+}
+
+function append(path: string, entry: ConsultRequest): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const previous = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${previous}${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    const fd = openSync(temp, 'r');
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(temp, path);
+  } catch (error) {
+    try { unlinkSync(temp); } catch { /* no temp file to remove */ }
+    throw error;
+  }
+}
+
+function records(path: string): ConsultRequest[] {
+  try {
+    return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line) as ConsultRequest);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+function rejected(field: string): Response {
+  debug.log('consult.request', 'rejected', { field });
+  return jsonResponse({ error: 'bad_request', field }, 400);
+}
+
+function singleLine(value: string): string {
+  return value.trim().replace(/[\r\n\u2028\u2029]+/g, ' ');
+}
+
+export async function handleConsultRequests(req: Request, deps: ConsultRequestsDeps = {}): Promise<Response> {
+  if (req.method !== 'GET' && req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  const path = file((deps.root ?? effectiveInstanceRoot)());
+  if (req.method === 'GET') {
+    const rawLimit = new URL(req.url).searchParams.get('limit');
+    const limit = rawLimit === null ? 20 : Number(rawLimit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) return rejected('limit');
+    try {
+      const items = records(path).reverse().slice(0, limit).map(({ receiptId, name, org, kind, interest, receivedAt }) =>
+        ({ receiptId, name, org, kind, interest, receivedAt }));
+      return jsonResponse({ items });
+    } catch {
+      return jsonResponse({ error: 'journal-unavailable' }, 503);
+    }
+  }
+
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return rejected('body'); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return rejected('body');
+  const input = body as Record<string, unknown>;
+  for (const field of ['name', 'contact'] as const) {
+    if (typeof input[field] !== 'string' || !input[field].trim()) return rejected(field);
+  }
+  if (input.org !== undefined && (typeof input.org !== 'string' || !input.org.trim())) return rejected('org');
+  if (input.kind !== 'company' && input.kind !== 'personal') return rejected('kind');
+  if (input.interest !== 'A' && input.interest !== 'B') return rejected('interest');
+  if (input.consent !== true) return rejected('consent');
+
+  const entry: ConsultRequest = {
+    receiptId: `R-${randomUUID()}`,
+    name: singleLine(input.name as string),
+    org: typeof input.org === 'string' ? singleLine(input.org) : null,
+    kind: input.kind,
+    interest: input.interest,
+    contact: (input.contact as string).trim(),
+    consent: true,
+    receivedAt: (deps.now ?? (() => new Date().toISOString()))(),
+  };
+  try { append(path, entry); }
+  catch {
+    debug.log('consult.request', 'rejected', { field: 'journal' });
+    return jsonResponse({ error: 'journal-unavailable' }, 503);
+  }
+  debug.log('consult.request', 'accepted', { receiptId: entry.receiptId });
+  try {
+    (deps.send ?? sendOutbound)(
+      `📮 상담 문의 ${entry.receiptId} · ${entry.name}(${entry.kind === 'personal' ? '개인' : (entry.org ?? '회사')}) · 관심 ${entry.interest}\n앱에서 보기`,
+      'alert',
+    );
+  } catch { /* the local receipt remains accepted if delivery is unavailable */ }
+  return jsonResponse({ receiptId: entry.receiptId, receivedAt: entry.receivedAt }, 202);
+}

package/src/nexus/api/discord-trigger-bot.ts

@@ -66,6 +66,8 @@ export interface NexusDiscordTriggerBotOpts {
    *  commands (/cc·/fork·/voice-join·…) route into the same composed
    *  message pipeline. Absent ⇒ interactions ignored (legacy). */
   onInteraction?: (raw: Record<string, unknown>) => void | Promise<void>;
+  /** EV12c — guild text channels answered like DMs (`discord.chatChannels`). Absent ⇒ DM-only. */
+  guildTextChannels?: string[];
   /** Optional logger. Defaults to `[discord/trigger]` prefix. */
   log?: (msg: string) => void;
   /** Test seam — pre-built DiscordBot (factory skips construction +
@@ -156,6 +158,7 @@ export function createNexusDiscordTriggerBot(
   const bot = opts.bot ?? new DiscordBot({
     token: opts.token,
     allowedUsers: opts.allowedUsers,
+    ...(opts.guildTextChannels?.length ? { guildTextChannels: opts.guildTextChannels } : {}),
     // Chat path: the injected self-turn handler (M4b nexus wire) or the
     // legacy trigger-only no-op. Workflows wanting a chat reply can
     // still declare a `chatTrigger` (routes via `/v1/workflows/chat/*`).

package/src/nexus/api/exec-requests.ts

@@ -0,0 +1,51 @@
+import { extname } from 'node:path';
+import { ExecRequestRunner } from '../../exec-requests/runner.js';
+import { jsonResponse } from './json-response.js';
+
+const mime: Record<string, string> = {
+  '.pdf': 'application/pdf', '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp',
+  '.md': 'text/markdown; charset=utf-8', '.txt': 'text/plain; charset=utf-8',
+};
+
+export async function handleExecRequests(req: Request, runner: ExecRequestRunner): Promise<Response> {
+  const path = new URL(req.url).pathname;
+  if (path === '/v1/exec-requests') {
+    if (req.method === 'POST') {
+      let body: unknown;
+      try { body = await req.json(); } catch { return jsonResponse({ error: 'bad_request' }, 400); }
+      const text = body && typeof body === 'object' && !Array.isArray(body) ? (body as { text?: unknown }).text : undefined;
+      if (typeof text !== 'string' || !text.trim()) return jsonResponse({ error: 'bad_request', reason: 'text required' }, 400);
+      const item = runner.submit(text.trim());
+      return jsonResponse({ id: item.id, status: 'planning' }, 202);
+    }
+    if (req.method === 'GET') return jsonResponse({ items: runner.store.list().map(item => {
+      const current = runner.get(item.id) ?? item;
+      return { id: current.id, text: current.text, createdAt: current.createdAt, status: current.status,
+        seats: current.seats.map(({ seat, title, status }) => ({ seat, title, status })), resultCount: current.results.length };
+    }) });
+    return jsonResponse({ error: 'method-not-allowed' }, 405);
+  }
+  const file = /^\/v1\/exec-requests\/([^/]+)\/files\/([^/]+)$/.exec(path);
+  if (file) {
+    if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+    let id: string, name: string;
+    try { id = decodeURIComponent(file[1]!); name = decodeURIComponent(file[2]!); }
+    catch { return jsonResponse({ error: 'not-found' }, 404); }
+    const path = runner.file(id, name);
+    if (!path) return jsonResponse({ error: 'not-found' }, 404);
+    return new Response(Bun.file(path), { headers: { 'content-type': mime[extname(path).toLowerCase()] ?? 'application/octet-stream', 'x-content-type-options': 'nosniff' } });
+  }
+  const detail = /^\/v1\/exec-requests\/([^/]+)$/.exec(path);
+  if (detail) {
+    if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+    let id: string;
+    try { id = decodeURIComponent(detail[1]!); } catch { return jsonResponse({ error: 'not-found' }, 404); }
+    const item = runner.get(id);
+    if (!item) return jsonResponse({ error: 'not-found' }, 404);
+    const { seats, ...rest } = item;
+    return jsonResponse({ ...rest, seats: seats.map(({ seat, title, status, graphId, runId, reason }) =>
+      ({ seat, title, status, graphId, runId, ...(reason ? { reason } : {}) })) });
+  }
+  return jsonResponse({ error: 'not-found' }, 404);
+}

package/src/nexus/api/field-uploads.ts

@@ -0,0 +1,180 @@
+// 현장 업로드 입구 — POST/GET /v1/field/uploads (owner 전용).
+// 저장 규칙은 src/field/field-media.ts 가 유일한 정본이고 텔레그램 `#현장` 도 같은 함수를 쓴다.
+
+import { debug } from '../../debug/log.js';
+import { readFieldReelStatus, scheduleFieldReel, fieldReelFile, hasFieldReelFile, type FieldReelOptions } from '../../field/field-reel.js';
+import { getElanousConfigDir } from '../../elanous-config-dir.js';
+import {
+  FIELD_MAX_FILE_BYTES,
+  FIELD_MAX_REQUEST_BYTES,
+  FieldUploadError,
+  defaultFieldEvent,
+  fieldEventDir,
+  isFieldSlug,
+  listFieldMedia,
+  saveFieldMedia,
+  type FieldMediaInput,
+} from '../../field/field-media.js';
+import { jsonResponse } from './json-response.js';
+
+export const FIELD_UPLOADS_PATH = '/v1/field/uploads';
+export const FIELD_REEL_PATH = '/v1/field/reel';
+export const FIELD_REEL_FILE_PATH = '/v1/field/reel/file';
+const reelUrl = (event: string) => `${FIELD_REEL_FILE_PATH}?event=${encodeURIComponent(event)}`;
+
+/** 멀티파트 경계·헤더 여유. */
+const MULTIPART_SLACK_BYTES = 4 * 1024 * 1024;
+/** JSON 본문은 base64(×4/3) 라 더 크다. */
+const JSON_MAX_BODY_BYTES = Math.ceil((FIELD_MAX_REQUEST_BYTES * 4) / 3) + MULTIPART_SLACK_BYTES;
+/** Bun.serve 의 `maxRequestBodySize`(기본 128 MB) — 이 입구의 JSON 상한까지 받도록 서버가 이 값을 쓴다. */
+export const FIELD_SERVER_MAX_BODY_BYTES = JSON_MAX_BODY_BYTES;
+
+interface FieldUploadsDeps {
+  authorize?: (request: Request) => boolean;
+  /** config 뿌리 — 기본 `getElanousConfigDir()`(데몬의 다른 저장소와 같은 해석). 시험은 temp 를 준다. */
+  rootDir?: () => string;
+  now?: () => Date;
+  reel?: FieldReelOptions;
+  /** 설정 `telegram.fieldDefaultEvent` — 앱이 «오늘» 행사 칸의 기본값으로 받는다(비면 field-<날짜>). */
+  configuredEvent?: () => string | undefined;
+}
+
+function errorResponse(error: FieldUploadError): Response {
+  return jsonResponse({ ok: false, error: error.code, reason: error.message }, error.status);
+}
+
+function parseCapturedAtList(values: FormDataEntryValue[]): Array<string | undefined> {
+  const strings = values.filter((v): v is string => typeof v === 'string');
+  if (strings.length === 1 && strings[0]!.trim().startsWith('[')) {
+    try {
+      const arr = JSON.parse(strings[0]!) as unknown;
+      if (Array.isArray(arr)) return arr.map((v) => (typeof v === 'string' || typeof v === 'number' ? String(v) : undefined));
+    } catch { /* 배열이 아니면 단일 값으로 */ }
+  }
+  return strings;
+}
+
+async function readMultipart(req: Request): Promise<FieldMediaInput[]> {
+  let form: FormData;
+  try { form = await req.formData(); }
+  catch { throw new FieldUploadError('bad-request', 'invalid multipart body'); }
+  const files = form.getAll('file').filter((v): v is File => typeof v !== 'string');
+  const captured = parseCapturedAtList(form.getAll('capturedAt'));
+  const captions = form.getAll('caption').filter((v): v is string => typeof v === 'string');
+  let total = 0;
+  const inputs: FieldMediaInput[] = [];
+  for (const [i, file] of files.entries()) {
+    if (file.size > FIELD_MAX_FILE_BYTES) throw new FieldUploadError('too-large', 'a file exceeds 100 MB');
+    total += file.size;
+    if (total > FIELD_MAX_REQUEST_BYTES) throw new FieldUploadError('too-large', 'the request exceeds 250 MB');
+    inputs.push({
+      originalName: file.name || 'media',
+      mimeType: file.type,
+      bytes: new Uint8Array(await file.arrayBuffer()),
+      ...(captured[i] ? { capturedAt: captured[i] } : {}),
+      ...((captions.length === 1 ? i === 0 : i < captions.length) ? { caption: captions[i] } : {}),
+    });
+  }
+  return inputs;
+}
+
+async function readJson(req: Request): Promise<FieldMediaInput[]> {
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { throw new FieldUploadError('bad-request', 'JSON body required'); }
+  const files = body && typeof body === 'object' && !Array.isArray(body) ? (body as { files?: unknown }).files : undefined;
+  if (!Array.isArray(files)) throw new FieldUploadError('bad-request', 'files[] required');
+  return files.map((raw) => {
+    const f = (raw ?? {}) as Record<string, unknown>;
+    if (typeof f.name !== 'string' || typeof f.dataBase64 !== 'string') {
+      throw new FieldUploadError('bad-request', 'each file needs name and dataBase64');
+    }
+    // base64 길이로 먼저 거른다 — 파일 상한(FIELD_MAX_FILE_BYTES)을 넘는 것을 디코드하지 않는다.
+    if (Math.floor((f.dataBase64.length * 3) / 4) > FIELD_MAX_FILE_BYTES + 3) {
+      throw new FieldUploadError('too-large', 'a file exceeds 100 MB');
+    }
+    const capturedAt = typeof f.capturedAt === 'string' || typeof f.capturedAt === 'number' ? f.capturedAt : undefined;
+    return {
+      originalName: f.name,
+      ...(typeof f.mimeType === 'string' ? { mimeType: f.mimeType } : {}),
+      bytes: new Uint8Array(Buffer.from(f.dataBase64, 'base64')),
+      ...(capturedAt !== undefined ? { capturedAt } : {}),
+      ...(typeof f.caption === 'string' ? { caption: f.caption } : {}),
+    };
+  });
+}
+
+export async function handleFieldUploads(req: Request, deps: FieldUploadsDeps = {}): Promise<Response> {
+  const url = new URL(req.url);
+  if (![FIELD_UPLOADS_PATH, FIELD_REEL_PATH, FIELD_REEL_FILE_PATH].includes(url.pathname)) return jsonResponse({ error: 'not-found' }, 404);
+  if (!deps.authorize?.(req)) return jsonResponse({ error: 'unauthorized' }, 401);
+  const rootDir = (deps.rootDir ?? getElanousConfigDir)();
+  const event = url.searchParams.get('event') ?? '';
+  // event 없는 GET = 기본 행사 이름만(앱 «오늘» 행사 칸 · 텔레그램 `#현장` 과 같은 기본).
+  if (req.method === 'GET' && !url.searchParams.has('event')) {
+    const defaultEvent = defaultFieldEvent((deps.configuredEvent ?? (() => undefined))(), (deps.now ?? (() => new Date()))());
+    return jsonResponse({ defaultEvent });
+  }
+  if (!isFieldSlug(event)) return errorResponse(new FieldUploadError('bad-slug', 'event slug must match ^[a-z0-9][a-z0-9._-]{0,63}$'));
+
+  const dir = fieldEventDir(rootDir, event);
+  if (url.pathname !== FIELD_UPLOADS_PATH && req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  if (url.pathname === FIELD_REEL_PATH) {
+    const status = readFieldReelStatus(dir);
+    if (!status) return jsonResponse({ error: 'not-found' }, 404);
+    return jsonResponse({ event, state: status.state, items: status.items,
+      ...(status.seconds !== undefined ? { seconds: status.seconds } : {}),
+      ...(status.finishedAt ? { finishedAt: status.finishedAt } : {}),
+      ...(status.state === 'failed' && status.error ? { error: status.error } : {}),
+      ...(status.state === 'done' && hasFieldReelFile(fieldReelFile(dir)) ? { url: reelUrl(event) } : {}) });
+  }
+  if (url.pathname === FIELD_REEL_FILE_PATH) {
+    const status = readFieldReelStatus(dir);
+    const file = fieldReelFile(dir);
+    if (status?.state !== 'done' || !hasFieldReelFile(file)) return jsonResponse({ error: 'not-found' }, 404);
+    return new Response(Bun.file(file), { headers: { 'content-type': 'video/mp4' } });
+  }
+  if (req.method === 'GET') {
+    const files = listFieldMedia(dir);
+    const status = readFieldReelStatus(dir);
+    debug.log('field.upload', 'listed', { count: files.length });
+    return jsonResponse({ event, count: files.length, files,
+      ...(status ? { reel: { status: status.state, updatedAt: status.updatedAt,
+        ...(status.state === 'done' && hasFieldReelFile(fieldReelFile(dir)) ? { url: reelUrl(event) } : {}) } } : {}) });
+  }
+  if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
+
+  const device = url.searchParams.get('device') ?? '';
+  if (!isFieldSlug(device)) return errorResponse(new FieldUploadError('bad-slug', 'device slug must match ^[a-z0-9][a-z0-9._-]{0,63}$'));
+
+  const contentType = (req.headers.get('content-type') ?? '').toLowerCase();
+  const isMultipart = contentType.startsWith('multipart/form-data');
+  const isJson = contentType.startsWith('application/json');
+  if (!isMultipart && !isJson) {
+    return errorResponse(new FieldUploadError('unsupported-media-type', 'use multipart/form-data or application/json'));
+  }
+  const declared = Number(req.headers.get('content-length') ?? '');
+  const bodyCap = isJson ? JSON_MAX_BODY_BYTES : FIELD_MAX_REQUEST_BYTES + MULTIPART_SLACK_BYTES;
+  if (Number.isFinite(declared) && declared > bodyCap) {
+    debug.log('field.upload', 'refused', { reason: 'too-large', declaredBytes: declared });
+    return errorResponse(new FieldUploadError('too-large', 'the request exceeds 250 MB'));
+  }
+
+  try {
+    const inputs = isMultipart ? await readMultipart(req) : await readJson(req);
+    const caption = url.searchParams.get('caption') ?? undefined;
+    const result = saveFieldMedia(inputs, { rootDir, event, device, ...(caption ? { caption } : {}), ...(deps.now ? { now: deps.now } : {}) });
+    debug.log('field.upload', 'saved', {
+      surface: 'http', files: result.saved.length, bytes: result.saved.reduce((n, s) => n + s.bytes, 0), count: result.count,
+    });
+    scheduleFieldReel(result.dir, deps.reel);
+    return jsonResponse({ ok: true, event, saved: result.saved, count: result.count });
+  } catch (error) {
+    if (error instanceof FieldUploadError) {
+      debug.log('field.upload', 'refused', { surface: 'http', reason: error.code });
+      return errorResponse(error);
+    }
+    debug.log('field.upload', 'failed', { surface: 'http' });
+    throw error;
+  }
+}

package/src/nexus/api/graph-approvals-feed.ts

@@ -0,0 +1,140 @@
+// EV10d — «게시 대기» 피드 초안: 승인 노드가 `{"kind":"feed-preview"}` 이면 그 런의 현장폴더 초안
+// (`<folder>/feed/feed-draft.json`)이 정본이다(계약 = MK 10-01 · field-feed 그래프). 경로는 «런 상태의
+// input.folder» 에서만 구하고, 그 폴더는 `<configDir>/field/<slug>` 꼴일 때만 받는다(realpath 로 탈출 거부).
+// 사람의 «수정 저장»은 허용된 칸만 고쳐 그 파일을 덮는다 — 승인 상태는 바꾸지 않는다.
+import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, normalize, sep } from 'node:path';
+import { fieldEventDir, isFieldSlug } from '../../field/field-media.js';
+import type { GraphRunState } from '../../graph-runner/runner.js';
+
+export interface FeedSlide { image: string; caption: string; include: boolean; [key: string]: unknown }
+export interface FeedDraft {
+  kind: 'feed-draft';
+  version: 1;
+  revision: number;
+  updatedAt: string;
+  updatedBy: string;
+  slides: FeedSlide[];
+  caption: { hook: string; body: string };
+  hashtags: string[];
+  cover: { text: string; sub: string; image?: string; [key: string]: unknown };
+  location: string | null;
+  reel: string | null;
+  brand?: { name?: string; handle?: string; avatar?: string | null };
+  [key: string]: unknown;
+}
+
+/** Fields a person may change from the PWA — everything else (rendered*, source, folder…) is preserved. */
+export interface FeedEdit {
+  slides: Array<{ image: string; caption?: string; include?: boolean }>;
+  caption: { hook: string; body: string };
+  hashtags: string[];
+  cover: { text: string; sub: string };
+  location: string | null;
+}
+
+export const FEED_DRAFT_FILE = join('feed', 'feed-draft.json');
+
+export function isFeedPreviewMessage(message: string): boolean {
+  try {
+    const parsed = JSON.parse(message) as unknown;
+    return !!parsed && typeof parsed === 'object' && (parsed as { kind?: unknown }).kind === 'feed-preview';
+  } catch { return false; }
+}
+
+function real(path: string): string | null {
+  try { return realpathSync(path); } catch { return null; }
+}
+
+/** The run's field folder when it is exactly `<configDir>/field/<slug>` (after resolving links), else null. */
+export function feedFolderFor(state: Pick<GraphRunState, 'input'>, configDir: string): string | null {
+  const input = state.input as { folder?: unknown } | undefined;
+  const folder = typeof input?.folder === 'string' ? input.folder : null;
+  if (!folder) return null;
+  const slug = basename(folder);
+  if (!isFieldSlug(slug)) return null;
+  const resolved = real(folder);
+  const expected = real(fieldEventDir(configDir, slug));
+  if (!resolved || !expected || resolved !== expected) return null;
+  if (dirname(resolved) !== real(join(configDir, 'field'))) return null;
+  return resolved;
+}
+
+function str(value: unknown): string { return typeof value === 'string' ? value : ''; }
+
+export function readFeedDraft(folder: string): FeedDraft | null {
+  try {
+    const raw = JSON.parse(readFileSync(join(folder, FEED_DRAFT_FILE), 'utf8')) as Partial<FeedDraft>;
+    if (raw.kind !== 'feed-draft' || raw.version !== 1 || !Array.isArray(raw.slides)) return null;
+    return raw as FeedDraft;
+  } catch { return null; }
+}
+
+export type FeedEditResult = { ok: true; draft: FeedDraft } | { ok: false; error: string };
+
+/** Apply a person's edit to the current draft. Slides must be the same set of images (order may change,
+ *  removal is `include:false`), so no new path can enter the draft. */
+export function applyFeedEdit(current: FeedDraft, edit: unknown, now = new Date()): FeedEditResult {
+  if (!edit || typeof edit !== 'object') return { ok: false, error: 'bad_request' };
+  const e = edit as Partial<FeedEdit>;
+  if (!Array.isArray(e.slides) || !e.caption || typeof e.caption !== 'object' || !Array.isArray(e.hashtags)
+    || !e.cover || typeof e.cover !== 'object') return { ok: false, error: 'bad_request' };
+  const original = new Map(current.slides.map((slide) => [slide.image, slide]));
+  const seen = new Set<string>();
+  const slides: FeedSlide[] = [];
+  for (const raw of e.slides) {
+    const image = str((raw as { image?: unknown })?.image);
+    const base = original.get(image);
+    if (!base || seen.has(image)) return { ok: false, error: 'unknown-image' };
+    seen.add(image);
+    const caption = (raw as { caption?: unknown }).caption;
+    const include = (raw as { include?: unknown }).include;
+    slides.push({ ...base, ...(typeof caption === 'string' ? { caption } : {}), ...(typeof include === 'boolean' ? { include } : {}) });
+  }
+  if (seen.size !== original.size) return { ok: false, error: 'missing-image' };
+  const location = e.location === null ? null : typeof e.location === 'string' ? e.location : current.location;
+  return {
+    ok: true,
+    draft: {
+      ...current,
+      slides,
+      caption: { ...current.caption, hook: str(e.caption.hook), body: str(e.caption.body) },
+      hashtags: e.hashtags.filter((tag): tag is string => typeof tag === 'string').map((tag) => tag.trim()).filter(Boolean),
+      cover: { ...current.cover, text: str(e.cover.text), sub: str(e.cover.sub) },
+      location,
+      revision: (Number.isFinite(current.revision) ? current.revision : 0) + 1,
+      updatedBy: 'human',
+      updatedAt: now.toISOString(),
+    },
+  };
+}
+
+export function writeFeedDraft(folder: string, draft: FeedDraft): void {
+  const target = join(folder, FEED_DRAFT_FILE);
+  const temp = `${target}.tmp-${process.pid}`;
+  writeFileSync(temp, `${JSON.stringify(draft, null, 2)}\n`);
+  renameSync(temp, target);
+}
+
+const MEDIA_RE = /^(?:feed\/[^/\\]+\.(?:png|jpe?g|webp)|reel\/reel-9x16\.mp4)$/i;
+
+/** Absolute file for a folder-relative media path, only `feed/*.png|jpg|jpeg|webp` and `reel/reel-9x16.mp4`. */
+export function resolveFeedMedia(folder: string, relative: string): string | null {
+  if (!relative || relative.startsWith('/') || relative.includes('\\') || relative.includes('\0')) return null;
+  const clean = normalize(relative).split(sep).join('/');
+  if (clean !== relative || !MEDIA_RE.test(clean)) return null;
+  const file = join(folder, clean);
+  if (!existsSync(file)) return null;
+  const resolved = real(file);
+  const root = real(folder);
+  if (!resolved || !root || !resolved.startsWith(`${root}${sep}`)) return null;
+  return resolved;
+}
+
+export function mediaContentType(path: string): string {
+  const lower = path.toLowerCase();
+  if (lower.endsWith('.png')) return 'image/png';
+  if (lower.endsWith('.webp')) return 'image/webp';
+  if (lower.endsWith('.mp4')) return 'video/mp4';
+  return 'image/jpeg';
+}