fuli-context 0.2.0

package/src/graphiti/source-marker.js

@@ -0,0 +1,142 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { DEFAULT_FULI_PORT } from '../defaults.js';
+
+const MAX_CITATIONS = 1;
+const DEFAULT_CONSOLE_URL = `http://127.0.0.1:${DEFAULT_FULI_PORT}`;
+
+export function sourceConsoleUrl(runtimeConfigPath, {
+  readText = (path) => readFileSync(path, 'utf8')
+} = {}) {
+  if (!runtimeConfigPath) return DEFAULT_CONSOLE_URL;
+  try {
+    const statePath = join(dirname(resolve(runtimeConfigPath)), 'graph-runtime-state.json');
+    const state = JSON.parse(readText(statePath));
+    return safeLoopbackOrigin(state?.url) ?? DEFAULT_CONSOLE_URL;
+  } catch {
+    return DEFAULT_CONSOLE_URL;
+  }
+}
+
+export function createFuliSourceMarker({
+  consoleUrl = DEFAULT_CONSOLE_URL,
+  facts = [],
+  entities = []
+} = {}) {
+  const citations = uniqueCitations([
+    ...facts.map(factCitation),
+    ...entities.map(entityCitation)
+  ].filter(Boolean));
+  const status = citations.length ? 'matched' : 'no_match';
+  return {
+    required: true,
+    label: 'FULI 来源',
+    status,
+    count: citations.length,
+    leadMarkdown: sourceLeadMarkdown({ consoleUrl, citations }),
+    markdown: sourceMarkerMarkdown({ consoleUrl, citations })
+  };
+}
+
+function factCitation(fact) {
+  return citation({
+    scope: fact.scope,
+    spaceId: fact.spaceId ?? fact.space_id,
+    itemKind: 'relationship',
+    itemId: fact.id,
+    title: [fact.source_entity, fact.target_entity].filter(Boolean).join(' → ') ||
+      fact.fact || '关系知识'
+  });
+}
+
+function entityCitation(entity) {
+  return citation({
+    scope: entity.scope,
+    spaceId: entity.spaceId ?? entity.space_id,
+    itemKind: 'entity',
+    itemId: entity.id,
+    title: entity.name || entity.summary || '实体知识'
+  });
+}
+
+function citation({ scope, spaceId, itemKind, itemId, title }) {
+  if (!['personal', 'project'].includes(scope) || !spaceId || !itemId) return null;
+  return {
+    scope,
+    spaceId: String(spaceId),
+    itemKind,
+    itemId: String(itemId),
+    title: singleLine(title)
+  };
+}
+
+function uniqueCitations(citations) {
+  const seen = new Set();
+  return citations.filter(({ scope, spaceId, itemKind, itemId }) => {
+    const key = `${scope}:${spaceId}:${itemKind}:${itemId}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function sourceLeadMarkdown({ consoleUrl, citations }) {
+  if (!citations.length) {
+    const origin = safeLoopbackOrigin(consoleUrl) ?? DEFAULT_CONSOLE_URL;
+    return `**[◇ FULI · 已检索，未命中](${origin}/)**`;
+  }
+  return `**[🌠 FULI · 知识增强](${knowledgeUrl(consoleUrl, citations[0])})**`;
+}
+
+function sourceMarkerMarkdown({ consoleUrl, citations }) {
+  if (!citations.length) {
+    return [
+      '**FULI 来源 · 未命中**',
+      '',
+      `- [打开 Fuli](${safeLoopbackOrigin(consoleUrl) ?? DEFAULT_CONSOLE_URL}/)`
+    ].join('\n');
+  }
+  const shown = citations.slice(0, MAX_CITATIONS);
+  const hidden = citations.length - shown.length;
+  return [
+    `**FULI 来源 · ${citations.length} 条**`,
+    '',
+    ...shown.map((item) =>
+      `- [${markdownLabel(item.title)}](${knowledgeUrl(consoleUrl, item)})`
+    ),
+    ...(hidden ? [`- 另有 ${hidden} 条命中，可在 Fuli 中查看`] : [])
+  ].join('\n');
+}
+
+function knowledgeUrl(consoleUrl, { scope, spaceId, itemKind, itemId }) {
+  const origin = safeLoopbackOrigin(consoleUrl) ?? DEFAULT_CONSOLE_URL;
+  const segments = ['knowledge', scope, spaceId, itemKind, itemId]
+    .map((segment) => encodeURIComponent(segment));
+  return `${origin}/#/${segments.join('/')}`;
+}
+
+function safeLoopbackOrigin(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'http:') return null;
+    if (!['127.0.0.1', 'localhost', '::1', '[::1]'].includes(url.hostname)) return null;
+    if (url.username || url.password) return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
+function singleLine(value) {
+  return String(value ?? '知识记录').replace(/[\r\n\t]+/g, ' ').trim().slice(0, 120) ||
+    '知识记录';
+}
+
+function markdownLabel(value) {
+  return singleLine(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replace(/([\\[\]])/g, '\\$1');
+}

package/src/http/api-router.js

@@ -0,0 +1,133 @@
+import { readJson, sendJson } from './response.js';
+import { handleLensRequest } from './lens-route.js';
+import { handleGraphApiRequest } from './graph-api-router.js';
+
+export async function handleApiRequest({ request, response, app }) {
+  const url = new URL(request.url, 'http://127.0.0.1');
+
+  if (url.pathname === '/api/health' && request.method === 'GET') {
+    sendJson(response, 200, {
+      status: 'ready',
+      service: 'fuli-local-console',
+      pid: process.pid
+    });
+    return true;
+  }
+
+  if (app.graphiti) {
+    return handleGraphApiRequest({ request, response, url, app });
+  }
+
+  if (handleLensRequest({ request, response, url, app })) return true;
+
+  if (url.pathname === '/api/state' && request.method === 'GET') {
+    sendJson(response, 200, app.state());
+    return true;
+  }
+
+  if (url.pathname === '/api/spaces' && request.method === 'POST') {
+    const body = await readJson(request);
+    const space = app.createSpace(body.name, body.kind, body.description ?? null);
+    sendJson(response, 200, { space });
+    return true;
+  }
+
+  if (url.pathname === '/api/bootstrap' && request.method === 'POST') {
+    sendJson(response, 200, app.bootstrap());
+    return true;
+  }
+
+  if (url.pathname === '/api/subscriptions' && request.method === 'POST') {
+    const body = await readJson(request);
+    const subscription = app.subscribe(
+      body.personalSpaceId,
+      body.spaceId,
+      body.mode ?? 'latest'
+    );
+    sendJson(response, 200, { subscription });
+    return true;
+  }
+
+  if (url.pathname === '/api/remember' && request.method === 'POST') {
+    const body = await readJson(request);
+    const result = app.remember({
+      personalSpaceId: app.requireSpaceId({
+        id: body.personalSpaceId,
+        name: body.personalSpaceName,
+        label: 'Personal space'
+      }),
+      targetSpaceId: optionalSpaceId(app, {
+        id: body.targetSpaceId,
+        name: body.targetSpaceName,
+        label: 'Target space'
+      }),
+      sourceKind: body.sourceKind ?? 'agent',
+      body: body.body,
+      sourceUri: body.sourceUri ?? null
+    });
+    sendJson(response, 200, result);
+    return true;
+  }
+
+  if (url.pathname === '/api/observe/git-diff' && request.method === 'POST') {
+    const body = await readJson(request);
+    const result = app.observe({
+      personalSpaceId: body.personalSpaceId,
+      targetSpaceId: body.targetSpaceId || null,
+      cwd: body.cwd ?? process.cwd()
+    });
+    sendJson(response, 200, result);
+    return true;
+  }
+
+  const candidateDecisionMatch = url.pathname.match(/^\/api\/candidates\/([^/]+)\/decision$/);
+  if (candidateDecisionMatch && request.method === 'POST') {
+    const body = await readJson(request);
+    const candidate = app.decideCandidate(candidateDecisionMatch[1], body.decision);
+    sendJson(response, 200, { candidate });
+    return true;
+  }
+
+  if (url.pathname === '/api/search' && request.method === 'GET') {
+    const result = app.search({
+      personalSpaceId: requiredSpaceId(app, {
+        id: url.searchParams.get('personalSpaceId'),
+        name: url.searchParams.get('personalSpaceName'),
+        label: 'Personal space'
+      }),
+      query: url.searchParams.get('q') ?? '',
+      includeHistorical: url.searchParams.get('historical') === 'true'
+    });
+    sendJson(response, 200, result);
+    return true;
+  }
+
+  if (url.pathname === '/api/context-pack' && request.method === 'GET') {
+    const result = app.contextPack({
+      personalSpaceId: requiredSpaceId(app, {
+        id: url.searchParams.get('personalSpaceId'),
+        name: url.searchParams.get('personalSpaceName'),
+        label: 'Personal space'
+      }),
+      spaceId: requiredSpaceId(app, {
+        id: url.searchParams.get('spaceId'),
+        name: url.searchParams.get('spaceName'),
+        label: 'Space'
+      }),
+      query: url.searchParams.get('q') ?? ''
+    });
+    sendJson(response, 200, result);
+    return true;
+  }
+
+  return false;
+}
+
+function requiredSpaceId(app, input) {
+  return app.requireSpaceId(input);
+}
+
+function optionalSpaceId(app, input) {
+  if (!input.id && !input.name) return null;
+  return requiredSpaceId(app, input);
+}

package/src/http/bounded-json-array.js

@@ -0,0 +1,19 @@
+export function selectBoundedJsonArray(items, budget) {
+  const selected = [];
+  let usedBytes = Buffer.byteLength('[]', 'utf8');
+  let truncated = false;
+
+  for (const item of items) {
+    const serialized = JSON.stringify(item);
+    const itemBytes = Buffer.byteLength(serialized, 'utf8');
+    const nextBytes = usedBytes + itemBytes + (selected.length ? 1 : 0);
+    if (nextBytes > budget) {
+      truncated = true;
+      continue;
+    }
+    selected.push(item);
+    usedBytes = nextBytes;
+  }
+
+  return { items: selected, usedBytes, truncated };
+}

package/src/http/error-mapping.js

@@ -0,0 +1,36 @@
+import {
+  ApplicationError,
+  ApplicationErrorCode
+} from '../app/application-error.js';
+import { JsonBodyTooLargeError } from './response.js';
+import { ProviderRequestError } from '../graphiti/provider-client.js';
+
+const BAD_REQUEST_CODES = new Set([
+  ApplicationErrorCode.NOT_FOUND,
+  ApplicationErrorCode.VALIDATION
+]);
+
+export function mapHttpError(error) {
+  if (error instanceof JsonBodyTooLargeError) {
+    return { status: 413, body: { error: 'Request body too large' } };
+  }
+
+  if (error instanceof SyntaxError) {
+    return { status: 400, body: { error: 'Malformed JSON' } };
+  }
+
+  if (error instanceof ApplicationError && BAD_REQUEST_CODES.has(error.code)) {
+    return { status: 400, body: { error: error.message } };
+  }
+
+  if (error instanceof ProviderRequestError) {
+    const status = error.status >= 400 && error.status <= 599 ? error.status : 502;
+    return { status, body: { error: error.message, code: error.code } };
+  }
+
+  if (error instanceof TypeError) {
+    return { status: 400, body: { error: error.message } };
+  }
+
+  return { status: 500, body: { error: 'Internal server error' } };
+}

package/src/http/graph-api-router.js

@@ -0,0 +1,257 @@
+import { readJson, sendJson } from './response.js';
+
+export async function handleGraphApiRequest({ request, response, url, app }) {
+  if (url.pathname === '/api/state' && request.method === 'GET') {
+    sendJson(response, 200, await app.state());
+    return true;
+  }
+  if (url.pathname === '/api/capture-policy' && request.method === 'GET') {
+    sendJson(response, 200, app.getCapturePolicy());
+    return true;
+  }
+  if (url.pathname === '/api/capture-policy' && request.method === 'PATCH') {
+    sendJson(response, 200, app.updateCapturePolicy(await readJson(request)));
+    return true;
+  }
+  if (url.pathname === '/api/agent-access-policy' && request.method === 'GET') {
+    sendJson(response, 200, app.getAgentAccessPolicy());
+    return true;
+  }
+  if (url.pathname === '/api/agent-access-policy' && request.method === 'PATCH') {
+    sendJson(response, 200, app.updateAgentAccessPolicy(await readJson(request)));
+    return true;
+  }
+  if (url.pathname === '/api/capture' && request.method === 'POST') {
+    sendJson(response, 200, await app.captureSessionKnowledge(await readJson(request)));
+    return true;
+  }
+  if (url.pathname === '/api/search' && request.method === 'GET') {
+    sendJson(response, 200, await app.searchKnowledge({
+      personalSpaceId: url.searchParams.get('personalSpaceId'),
+      query: url.searchParams.get('q') ?? '',
+      projectIds: url.searchParams.getAll('projectId'),
+      personalProjectId: url.searchParams.get('personalProjectId'),
+      contextPersonalProjectIds: url.searchParams.getAll('contextPersonalProjectId'),
+      limit: numberParam(url, 'limit', 12),
+      includeHistorical: url.searchParams.get('historical') === 'true',
+      includePending: url.searchParams.get('pending') === 'true' ||
+        url.searchParams.get('exploratory') === 'true'
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/graph' && request.method === 'GET') {
+    sendJson(response, 200, await app.getKnowledgeGraph({
+      spaceId: url.searchParams.get('spaceId'),
+      providerUrl: url.searchParams.get('providerUrl'),
+      personalProjectId: url.searchParams.get('personalProjectId'),
+      limit: numberParam(url, 'limit', 500)
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/preference-conflicts' && request.method === 'GET') {
+    sendJson(response, 200, await app.listPreferenceConflicts({
+      personalSpaceId: url.searchParams.get('personalSpaceId'),
+      status: url.searchParams.get('status'),
+      limit: numberParam(url, 'limit', 500)
+    }));
+    return true;
+  }
+  if (
+    url.pathname === '/api/preference-conflicts/defer'
+    && request.method === 'POST'
+  ) {
+    sendJson(response, 200, await app.deferPreferenceConflict({
+      ...(await readJson(request)),
+      operationActor: 'human'
+    }));
+    return true;
+  }
+  const completedPreferenceConflict = url.pathname.match(
+    /^\/api\/preference-conflicts\/([^/]+)\/complete$/
+  );
+  if (completedPreferenceConflict && request.method === 'POST') {
+    sendJson(response, 200, await app.completePreferenceConflict({
+      ...(await readJson(request)),
+      conflictId: decodeURIComponent(completedPreferenceConflict[1]),
+      operationActor: 'human'
+    }));
+    return true;
+  }
+  const assignment = url.pathname.match(
+    /^\/api\/knowledge\/(entity|relationship)\/([^/]+)\/assignment$/
+  );
+  if (assignment && request.method === 'POST') {
+    sendJson(response, 200, await app.reassignKnowledgeItem({
+      ...(await readJson(request)),
+      itemKind: assignment[1],
+      itemId: decodeURIComponent(assignment[2]),
+      operationActor: 'human'
+    }));
+    return true;
+  }
+  const preferenceScope = url.pathname.match(
+    /^\/api\/knowledge\/(entity|relationship)\/([^/]+)\/preference-scope$/
+  );
+  if (preferenceScope && request.method === 'POST') {
+    sendJson(response, 200, await app.setPersonalPreferenceScope({
+      ...(await readJson(request)),
+      itemKind: preferenceScope[1],
+      itemId: decodeURIComponent(preferenceScope[2]),
+      operationActor: 'human'
+    }));
+    return true;
+  }
+  const projectAction = url.pathname.match(
+    /^\/api\/knowledge\/(entity)\/([^/]+)\/project-action(\/preview)?$/
+  );
+  if (projectAction && request.method === 'POST') {
+    const body = await readJson(request);
+    const input = {
+      ...body,
+      itemKind: projectAction[1],
+      itemId: decodeURIComponent(projectAction[2]),
+      operationActor: 'human'
+    };
+    const result = projectAction[3]
+      ? await app.previewKnowledgeProjectAction(input)
+      : await app.applyKnowledgeProjectAction(input);
+    sendJson(response, 200, result);
+    return true;
+  }
+  if (url.pathname === '/api/knowledge/batch-confirmation' && request.method === 'POST') {
+    sendJson(
+      response,
+      200,
+      await app.confirmKnowledgeBatch({
+        ...(await readJson(request)),
+        operationActor: 'human'
+      })
+    );
+    return true;
+  }
+  const knowledgeItem = url.pathname.match(
+    /^\/api\/knowledge\/(entity|relationship)\/([^/]+)$/
+  );
+  if (knowledgeItem && request.method === 'PATCH') {
+    sendJson(response, 200, await app.reviseKnowledgeItem({
+      ...(await readJson(request)),
+      itemKind: knowledgeItem[1],
+      itemId: decodeURIComponent(knowledgeItem[2]),
+      operationActor: 'human'
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/subscriptions' && request.method === 'POST') {
+    sendJson(response, 200, await app.subscribePublicProject(await readJson(request)));
+    return true;
+  }
+  const subscription = url.pathname.match(/^\/api\/subscriptions\/([^/]+)$/);
+  if (subscription && request.method === 'DELETE') {
+    sendJson(response, 200, await app.unsubscribePublicProject({
+      personalSpaceId: url.searchParams.get('personalSpaceId'),
+      projectId: decodeURIComponent(subscription[1]),
+      providerUrl: url.searchParams.get('providerUrl')
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/personal-projects' && request.method === 'GET') {
+    sendJson(response, 200, await app.listPersonalProjects({
+      personalSpaceId: url.searchParams.get('personalSpaceId')
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/personal-projects' && request.method === 'PUT') {
+    sendJson(response, 200, await app.upsertPersonalProject(await readJson(request)));
+    return true;
+  }
+  if (url.pathname === '/api/projects/publish' && request.method === 'POST') {
+    sendJson(response, 200, await app.publishPersonalProject(await readJson(request)));
+    return true;
+  }
+  const projectReleases = url.pathname.match(/^\/api\/projects\/([^/]+)\/releases$/);
+  if (projectReleases && request.method === 'GET') {
+    sendJson(response, 200, await app.listProjectReleases({
+      projectId: decodeURIComponent(projectReleases[1]),
+      providerUrl: url.searchParams.get('providerUrl')
+    }));
+    return true;
+  }
+  const publicProject = url.pathname.match(/^\/api\/projects\/([^/]+)$/);
+  if (publicProject && request.method === 'DELETE') {
+    sendJson(response, 200, await app.deletePublicProject({
+      projectId: decodeURIComponent(publicProject[1]),
+      providerUrl: url.searchParams.get('providerUrl')
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/project-relations' && request.method === 'GET') {
+    sendJson(response, 200, await app.listProjectRelations({
+      projectId: url.searchParams.get('projectId'),
+      providerUrl: url.searchParams.get('providerUrl')
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/project-relations' && request.method === 'POST') {
+    sendJson(response, 200, await app.createProjectRelation(await readJson(request)));
+    return true;
+  }
+  const relationDecision = url.pathname.match(
+    /^\/api\/project-relations\/([^/]+)\/decision$/
+  );
+  if (relationDecision && request.method === 'POST') {
+    const body = await readJson(request);
+    sendJson(response, 200, await app.reviewProjectRelation({
+      ...body,
+      relationId: decodeURIComponent(relationDecision[1])
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/personal-review' && request.method === 'GET') {
+    sendJson(response, 200, await app.listPersonalReviewQueue({
+      personalSpaceId: url.searchParams.get('personalSpaceId'),
+      status: url.searchParams.get('status') ?? 'pending'
+    }));
+    return true;
+  }
+  const personalDecision = url.pathname.match(/^\/api\/personal-review\/([^/]+)\/decision$/);
+  if (personalDecision && request.method === 'POST') {
+    const body = await readJson(request);
+    sendJson(response, 200, await app.reviewPersonalDraft({
+      ...body,
+      draftId: decodeURIComponent(personalDecision[1])
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/review' && request.method === 'GET') {
+    sendJson(response, 200, await app.listReviewQueue({
+      projectId: url.searchParams.get('projectId'),
+      providerUrl: url.searchParams.get('providerUrl'),
+      status: url.searchParams.get('status') ?? 'pending'
+    }));
+    return true;
+  }
+  const decision = url.pathname.match(/^\/api\/review\/([^/]+)\/decision$/);
+  if (decision && request.method === 'POST') {
+    const body = await readJson(request);
+    sendJson(response, 200, await app.reviewProposal({
+      ...body,
+      proposalId: decodeURIComponent(decision[1])
+    }));
+    return true;
+  }
+  if (url.pathname === '/api/graphiti/status' && request.method === 'GET') {
+    sendJson(response, 200, await app.getGraphitiStatus());
+    return true;
+  }
+  return false;
+}
+
+function numberParam(url, name, fallback) {
+  const raw = url.searchParams.get(name);
+  if (raw === null) return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive integer`);
+  }
+  return value;
+}

package/src/http/lens-route.js

@@ -0,0 +1,50 @@
+import { ApplicationError, ApplicationErrorCode } from '../app/application-error.js';
+import { selectBoundedJsonArray } from './bounded-json-array.js';
+import { sendJson } from './response.js';
+
+const DEFAULT_BUDGET = 1200;
+const MAX_BUDGET = 16384;
+
+export function handleLensRequest({ request, response, url, app }) {
+  if (url.pathname !== '/api/lens' || request.method !== 'GET') return false;
+
+  const personalSpaceId = app.requireSpaceId({
+    id: url.searchParams.get('personalSpaceId'),
+    name: url.searchParams.get('personalSpaceName'),
+    label: 'Personal space'
+  });
+  const budget = parseBudget(url.searchParams.get('budget'));
+  const view = app.lens.getUserLensView({
+    personalSpaceId,
+    task: '',
+    budget,
+    includeObserved: true,
+    includeSuggested: false,
+    includeRestricted: false
+  });
+  const bounded = selectBoundedJsonArray(view.entries, budget);
+
+  sendJson(response, 200, {
+    personalSpaceId,
+    budget,
+    usedBytes: bounded.usedBytes,
+    truncated: view.truncated || bounded.truncated,
+    facts: bounded.items
+  });
+  return true;
+}
+
+function parseBudget(value) {
+  if (value === null) return DEFAULT_BUDGET;
+  if (!/^[1-9]\d*$/.test(value)) throw invalidBudget();
+  const budget = Number(value);
+  if (!Number.isSafeInteger(budget) || budget < 2 || budget > MAX_BUDGET) throw invalidBudget();
+  return budget;
+}
+
+function invalidBudget() {
+  return new ApplicationError(
+    ApplicationErrorCode.VALIDATION,
+    `Budget must be an integer between 2 and ${MAX_BUDGET}`
+  );
+}

package/src/http/request-policy.js

@@ -0,0 +1,41 @@
+import { sendJson } from './response.js';
+
+export function localServerAuthority(address) {
+  if (!address || typeof address === 'string') return null;
+  if (!Number.isSafeInteger(address.port) || address.port < 1 || address.port > 65535) {
+    return null;
+  }
+  return address.port === 80 ? '127.0.0.1' : `127.0.0.1:${address.port}`;
+}
+
+export function rejectDisallowedRequest({ request, response, authority }) {
+  const origin = request.headers.origin;
+  const fetchSite = request.headers['sec-fetch-site'];
+  if (
+    !authority ||
+    request.headers.host !== authority ||
+    (origin !== undefined && origin !== `http://${authority}`) ||
+    (typeof fetchSite === 'string' && fetchSite.toLowerCase() === 'cross-site')
+  ) {
+    sendJson(response, 403, { error: 'Forbidden' });
+    return true;
+  }
+
+  if (requiresJson(request) && !isJson(request.headers['content-type'])) {
+    sendJson(response, 415, { error: 'Unsupported media type' });
+    return true;
+  }
+
+  return false;
+}
+
+function requiresJson(request) {
+  if (request.method !== 'POST') return false;
+  const pathname = new URL(request.url, 'http://127.0.0.1').pathname;
+  return pathname.startsWith('/api/');
+}
+
+function isJson(contentType) {
+  if (typeof contentType !== 'string') return false;
+  return contentType.split(';', 1)[0].trim().toLowerCase() === 'application/json';
+}