wendkeep 0.69.0 → 0.70.0

package/src/observer-publish.mjs

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildProjectSnapshot } from './observer-snapshot.mjs';
+
+const OUTBOX_REL = join('.brain', 'observer-outbox');
+const REQUEST_TIMEOUT_MS = 500;
+
+function outboxDir(vaultBase) {
+  return join(vaultBase, OUTBOX_REL);
+}
+
+function eventPath(vaultBase, eventId) {
+  if (!/^obs-[a-f0-9]{24}$/.test(eventId)) throw new Error('event_id inválido para outbox.');
+  return join(outboxDir(vaultBase), `${eventId}.json`);
+}
+
+function atomicWrite(path, value) {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(value)}\n`, 'utf8');
+  renameSync(temp, path);
+}
+
+export function listOutbox(vaultBase) {
+  const dir = outboxDir(vaultBase);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => /^obs-[a-f0-9]{24}\.json$/.test(name))
+    .sort()
+    .flatMap((name) => {
+      try { return [JSON.parse(readFileSync(join(dir, name), 'utf8'))]; }
+      catch { return []; }
+    });
+}
+
+function queueOutbox(vaultBase, event) {
+  const dir = outboxDir(vaultBase);
+  mkdirSync(dir, { recursive: true });
+  const path = eventPath(vaultBase, event.event_id);
+  if (!existsSync(path)) atomicWrite(path, event);
+  return path;
+}
+
+function removeOutbox(vaultBase, eventId) {
+  const path = eventPath(vaultBase, eventId);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+async function postSnapshot(url, token, event) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${String(url).replace(/\/$/, '')}/v1/projects/${encodeURIComponent(event.project_id)}/snapshot`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(event),
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    let body = {};
+    try { body = JSON.parse(text); } catch { /* server error remains deterministic below */ }
+    if (!response.ok || !(body.accepted === true || body.duplicate === true)) {
+      throw new Error(`Observer respondeu HTTP ${response.status}.`);
+    }
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function retryObserverOutbox({ vaultBase, url, token } = {}) {
+  if (!url || !token) return { attempted: 0, confirmed: 0, pending: listOutbox(vaultBase).length };
+  let attempted = 0;
+  let confirmed = 0;
+  for (const event of listOutbox(vaultBase)) {
+    attempted += 1;
+    try {
+      await postSnapshot(url, token, event);
+      removeOutbox(vaultBase, event.event_id);
+      confirmed += 1;
+    } catch { /* preserve the event for a later retry */ }
+  }
+  return { attempted, confirmed, pending: listOutbox(vaultBase).length };
+}
+
+export async function publishObserverSnapshot({
+  vaultBase,
+  projectRoot,
+  url = process.env.WENDKEEP_OBSERVER_URL || '',
+  token = process.env.WENDKEEP_OBSERVER_TOKEN || '',
+  now = new Date(),
+} = {}) {
+  try {
+    const event = buildProjectSnapshot({ vaultBase, projectRoot, now });
+    if (!url) return { ok: true, skipped: true, queued: false, hookExitCode: 0, event_id: event.event_id };
+
+    await retryObserverOutbox({ vaultBase, url, token });
+    try {
+      const response = await postSnapshot(url, token, event);
+      return {
+        ok: true,
+        queued: false,
+        hookExitCode: 0,
+        event_id: event.event_id,
+        duplicate: response.duplicate === true,
+      };
+    } catch (error) {
+      queueOutbox(vaultBase, event);
+      return {
+        ok: false,
+        queued: true,
+        hookExitCode: 0,
+        event_id: event.event_id,
+        error: error.message,
+      };
+    }
+  } catch (error) {
+    return { ok: false, queued: false, hookExitCode: 0, error: error.message };
+  }
+}

package/src/observer-server.mjs

@@ -0,0 +1,203 @@
+import { createServer } from 'node:http';
+import { appendObserverEvent, getObserverProject, readObserverIndex, registerObserverProject } from './observer-store.mjs';
+import { MAX_SNAPSHOT_BYTES, validateObserverSnapshot } from './observer-snapshot.mjs';
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+const MAX_BODY_BYTES = MAX_SNAPSHOT_BYTES + 4096;
+
+function loopbackOnly(host) {
+  return LOOPBACK_HOSTS.has(String(host || '').toLowerCase());
+}
+
+function json(res, status, body) {
+  const content = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(content),
+  });
+  res.end(content);
+}
+
+function errorResponse(res, status, code, message) {
+  json(res, status, { error: { code, message } });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    let tooLarge = false;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      if (tooLarge) return;
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        tooLarge = true;
+        const error = new Error('corpo acima do limite.');
+        error.code = 'payload_too_large';
+        reject(error);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (!tooLarge) resolve(Buffer.concat(chunks).toString('utf8'));
+    });
+    req.on('error', reject);
+  });
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text || '{}'); }
+  catch {
+    const error = new Error('JSON inválido.');
+    error.code = 'invalid_json';
+    throw error;
+  }
+}
+
+function authorized(req, token) {
+  if (!token) return false;
+  const header = String(req.headers.authorization || '');
+  return header === `Bearer ${token}`
+    || req.headers['x-wendkeep-observer-token'] === token;
+}
+
+function pathParts(url) {
+  return new URL(url, 'http://127.0.0.1').pathname.split('/').filter(Boolean).map((part) => decodeURIComponent(part));
+}
+
+function projectIdFrom(parts) {
+  return parts[0] === 'v1' && parts[1] === 'projects' && parts[2] ? parts[2] : '';
+}
+
+export async function startObserverServer({
+  host = '127.0.0.1',
+  port = 8787,
+  dataDir,
+  token = process.env.WENDKEEP_OBSERVER_TOKEN || '',
+  allowNonLoopback = false,
+} = {}) {
+  if (!loopbackOnly(host) && !allowNonLoopback) {
+    throw new Error(`Observer HTTP aceita somente host loopback; recebido: ${host}`);
+  }
+  if (!dataDir) throw new Error('dataDir é obrigatório.');
+  const server = createServer(async (req, res) => {
+    try {
+      const parts = pathParts(req.url || '/');
+      if (req.method === 'GET' && parts.length === 1 && parts[0] === 'healthz') {
+        json(res, 200, { ok: true, service: 'wendkeep-observer', schema_version: 1 });
+        return;
+      }
+      if (!authorized(req, token)) {
+        errorResponse(res, 401, 'unauthorized', 'token local ausente ou inválido.');
+        return;
+      }
+      if (parts[0] !== 'v1' || parts[1] !== 'projects') {
+        errorResponse(res, 404, 'not_found', 'rota não encontrada.');
+        return;
+      }
+
+      if (parts.length === 2 && req.method === 'GET') {
+        const index = readObserverIndex(dataDir);
+        json(res, 200, {
+          schema_version: index.schema_version,
+          projects: index.projects.map(({ snapshot, ...summary }) => summary),
+        });
+        return;
+      }
+
+      const projectId = projectIdFrom(parts);
+      if (!projectId) {
+        errorResponse(res, 404, 'not_found', 'projeto não informado.');
+        return;
+      }
+
+      if (parts.length === 3 && req.method === 'GET') {
+        const project = getObserverProject(dataDir, projectId);
+        if (!project) {
+          errorResponse(res, 404, 'project_not_found', `projeto não encontrado: ${projectId}`);
+          return;
+        }
+        json(res, 200, project);
+        return;
+      }
+
+      if (parts.length === 3 && req.method === 'PUT') {
+        const body = parseJson(await readBody(req));
+        if (body.project_id !== projectId) {
+          errorResponse(res, 400, 'project_mismatch', 'project_id do corpo não corresponde à rota.');
+          return;
+        }
+        const result = registerObserverProject(dataDir, {
+          projectId,
+          projectName: body.project_name,
+          wendkeepVersion: body.wendkeep_version,
+        });
+        if (!result.registered) {
+          errorResponse(res, 400, 'invalid_project', result.errors.join(' '));
+          return;
+        }
+        json(res, 201, result.project);
+        return;
+      }
+
+      if (parts.length === 4 && parts[3] === 'changes' && req.method === 'GET') {
+        const project = getObserverProject(dataDir, projectId);
+        if (!project) {
+          errorResponse(res, 404, 'project_not_found', `projeto não encontrado: ${projectId}`);
+          return;
+        }
+        json(res, 200, { project_id: projectId, changes: project.snapshot?.changes || [] });
+        return;
+      }
+
+      if (parts.length === 4 && ['snapshot', 'snapshots'].includes(parts[3]) && req.method === 'POST') {
+        const body = parseJson(await readBody(req));
+        const validation = validateObserverSnapshot(body, { projectId });
+        if (!validation.ok) {
+          errorResponse(res, 400, 'invalid_snapshot', validation.errors.join(' '));
+          return;
+        }
+        const result = appendObserverEvent(dataDir, body);
+        if (!result.accepted && result.duplicate) {
+          json(res, 200, { accepted: false, duplicate: true, event_id: body.event_id });
+          return;
+        }
+        if (!result.accepted) {
+          const unregistered = result.errors.some((item) => /não registrado/.test(item));
+          errorResponse(res, unregistered ? 409 : 400, unregistered ? 'project_not_registered' : 'invalid_event', result.errors.join(' '));
+          return;
+        }
+        json(res, 201, { accepted: true, duplicate: false, event_id: body.event_id });
+        return;
+      }
+
+      errorResponse(res, 404, 'not_found', 'rota não encontrada.');
+    } catch (error) {
+      if (res.headersSent) return;
+      const status = error?.code === 'payload_too_large' ? 413 : error?.code === 'invalid_json' ? 400 : 500;
+      errorResponse(res, status, error?.code || 'observer_error', error?.message || 'erro interno do Observer.');
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve();
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(Number(port), host);
+  });
+
+  return {
+    server,
+    address: () => server.address(),
+    close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))),
+  };
+}

package/src/observer-snapshot.mjs

@@ -0,0 +1,153 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { allChangesState } from '../hooks/change-core.mjs';
+import { readControl, readSessionRegistry } from '../hooks/obsidian-common.mjs';
+import { runVaultHealth } from '../hooks/vault-health.mjs';
+import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+
+export const OBSERVER_SCHEMA_VERSION = 1;
+export const MAX_SNAPSHOT_BYTES = 32 * 1024;
+const MAX_TEXT = 160;
+
+function fail(message, code = 'WENDKEEP_OBSERVER_SNAPSHOT_INVALID') {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function safeText(value, max = MAX_TEXT) {
+  return String(value ?? '')
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/[A-Za-z]:[\\/][^\s"']*/g, '[REDACTED_PATH]')
+    .replace(/\\\\[^\s"']+/g, '[REDACTED_PATH]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+function isoNow(value) {
+  const date = value instanceof Date ? value : new Date(value ?? Date.now());
+  if (Number.isNaN(date.getTime())) throw fail('captured_at inválido.');
+  return date.toISOString();
+}
+
+function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function activeSessionSummary(vaultBase, control, registry) {
+  const entries = Object.entries(registry?.sessions || {})
+    .map(([sessionId, entry]) => ({ sessionId, entry }))
+    .sort((a, b) => String(b.entry?.last_seen || b.entry?.updated_at || '').localeCompare(String(a.entry?.last_seen || a.entry?.updated_at || '')));
+  const selected = entries.find(({ sessionId }) => sessionId === control?.session_id) || entries[0];
+  const entry = selected?.entry || {};
+  return {
+    status: safeText(control?.status || entry.status || 'inactive', 32),
+    session_id: safeText(control?.session_id || selected?.sessionId || '', 100),
+    provider: safeText(entry.provider || '', 32),
+    change_slug: safeText(entry.change_slug || '', 100),
+    last_seen: safeText(entry.last_seen || entry.updated_at || '', 40),
+  };
+}
+
+function healthSummary(vaultBase) {
+  try {
+    const health = runVaultHealth({ vaultBase });
+    return {
+      ok: health.ok === true,
+      status: safeText(health.memoryStatus || (health.ok ? 'healthy' : 'degraded'), 40),
+      failure_count: Array.isArray(health.failures) ? health.failures.length : 0,
+      warning_count: Array.isArray(health.warnings) ? health.warnings.length : 0,
+      registry_sessions: Number(health.metrics?.registrySessions || 0),
+      derived_notes: Number(health.metrics?.derivedNotes || 0),
+    };
+  } catch {
+    return {
+      ok: false,
+      status: 'unavailable',
+      failure_count: 1,
+      warning_count: 0,
+      registry_sessions: 0,
+      derived_notes: 0,
+    };
+  }
+}
+
+function hashEvent(snapshot) {
+  const canonical = JSON.stringify({ ...snapshot, event_id: undefined });
+  return `obs-${createHash('sha256').update(canonical).digest('hex').slice(0, 24)}`;
+}
+
+function hasForbiddenKey(value) {
+  if (!value || typeof value !== 'object') return false;
+  for (const [key, child] of Object.entries(value)) {
+    if (/(?:core|shared|digest|transcript|secret|token|prompt|raw|path|vault)/i.test(key)) return true;
+    if (hasForbiddenKey(child)) return true;
+  }
+  return false;
+}
+
+function hasAbsolutePath(value) {
+  if (typeof value === 'string') {
+    return /[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/]|(?:^|\s)\/(?:Users|home|mnt|var|tmp)\//.test(value);
+  }
+  if (!value || typeof value !== 'object') return false;
+  return Object.values(value).some(hasAbsolutePath);
+}
+
+export function validateObserverSnapshot(snapshot, { projectId = '' } = {}) {
+  const errors = [];
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    return { ok: false, errors: ['snapshot deve ser um objeto JSON.'] };
+  }
+  if (snapshot.schema_version !== OBSERVER_SCHEMA_VERSION) errors.push('schema_version incompatível.');
+  for (const key of ['event_id', 'project_id', 'project_name', 'wendkeep_version', 'captured_at']) {
+    if (typeof snapshot[key] !== 'string' || !snapshot[key].trim()) errors.push(`${key} ausente ou inválido.`);
+  }
+  if (projectId && snapshot.project_id !== projectId) errors.push('project_id não corresponde ao projeto registrado.');
+  if (!Array.isArray(snapshot.changes)) errors.push('changes deve ser uma lista.');
+  if (!snapshot.session || typeof snapshot.session !== 'object') errors.push('session ausente.');
+  if (!snapshot.health || typeof snapshot.health !== 'object') errors.push('health ausente.');
+  if (hasForbiddenKey(snapshot)) errors.push('snapshot contém campo não permitido.');
+  if (hasAbsolutePath(snapshot)) errors.push('snapshot contém caminho absoluto.');
+  const size = Buffer.byteLength(JSON.stringify(snapshot), 'utf8');
+  if (size > MAX_SNAPSHOT_BYTES) errors.push(`snapshot excede ${MAX_SNAPSHOT_BYTES} bytes.`);
+  return { ok: errors.length === 0, errors, size };
+}
+
+export function buildProjectSnapshot({ vaultBase, projectRoot = process.cwd(), now = new Date() } = {}) {
+  if (!vaultBase) throw fail('vaultBase é obrigatório.');
+  const project = readProjectForValidation(vaultBase);
+  if (!project.ok || !project.projectId) throw fail(project.errors?.join(' ') || 'PROJECT.json inválido.');
+  const control = readControl(vaultBase);
+  const registry = readSessionRegistry(vaultBase);
+  const changes = allChangesState(vaultBase).changes.map((change) => ({
+    slug: safeText(change.slug, 100),
+    current: change.current === true,
+    openTasks: Number(change.openCount || 0),
+    doneTasks: Number(change.doneCount || 0),
+    warning: safeText(change.warning || '', 120),
+  }));
+  const markerName = project.marker?.projectName || basename(projectRoot);
+  const snapshot = {
+    schema_version: OBSERVER_SCHEMA_VERSION,
+    event_id: '',
+    project_id: project.projectId,
+    projectId: project.projectId,
+    project_name: safeText(markerName || project.projectId, 100),
+    wendkeep_version: packageVersion(),
+    captured_at: isoNow(now),
+    session: activeSessionSummary(vaultBase, control, registry),
+    changes,
+    health: healthSummary(vaultBase),
+  };
+  snapshot.event_id = hashEvent(snapshot);
+  const validation = validateObserverSnapshot(snapshot, { projectId: project.projectId });
+  if (!validation.ok) throw fail(validation.errors.join(' '));
+  return snapshot;
+}

package/src/observer-store.mjs

@@ -0,0 +1,155 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MAX_SNAPSHOT_BYTES, OBSERVER_SCHEMA_VERSION, validateObserverSnapshot } from './observer-snapshot.mjs';
+
+export const OBSERVER_DATA_SCHEMA_VERSION = 1;
+export const OBSERVER_EVENTS_FILE = 'EVENTS.jsonl';
+export const OBSERVER_INDEX_FILE = 'INDEX.json';
+export const OBSERVER_PROJECTS_FILE = 'PROJECTS.json';
+
+function ensureDataDir(dataDir) {
+  if (!dataDir) throw new Error('dataDir é obrigatório.');
+  mkdirSync(dataDir, { recursive: true });
+}
+
+function atomicJson(path, value) {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  renameSync(temp, path);
+}
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return fallback; }
+}
+
+function projectIdValid(projectId) {
+  return typeof projectId === 'string'
+    && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,120}$/.test(projectId);
+}
+
+function registeredProjects(dataDir) {
+  const raw = readJson(join(dataDir, OBSERVER_PROJECTS_FILE), {
+    schema_version: OBSERVER_DATA_SCHEMA_VERSION,
+    projects: {},
+  });
+  return raw?.schema_version === OBSERVER_DATA_SCHEMA_VERSION && raw.projects && typeof raw.projects === 'object'
+    ? raw.projects
+    : {};
+}
+
+export function registerObserverProject(dataDir, {
+  projectId,
+  projectName = projectId,
+  wendkeepVersion = '',
+  registeredAt = new Date().toISOString(),
+} = {}) {
+  ensureDataDir(dataDir);
+  if (!projectIdValid(projectId)) return { registered: false, errors: ['project_id inválido.'] };
+  const projects = registeredProjects(dataDir);
+  const project = {
+    projectId,
+    projectName: String(projectName || projectId).replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, 120),
+    wendkeepVersion: String(wendkeepVersion || '').slice(0, 40),
+    registeredAt: String(registeredAt),
+  };
+  projects[projectId] = project;
+  atomicJson(join(dataDir, OBSERVER_PROJECTS_FILE), {
+    schema_version: OBSERVER_DATA_SCHEMA_VERSION,
+    projects,
+  });
+  return { registered: true, project };
+}
+
+export function listRegisteredObserverProjects(dataDir) {
+  return Object.values(registeredProjects(dataDir)).sort((a, b) => a.projectId.localeCompare(b.projectId));
+}
+
+function readEvents(dataDir) {
+  const path = join(dataDir, OBSERVER_EVENTS_FILE);
+  if (!existsSync(path)) return [];
+  const events = [];
+  const lines = readFileSync(path, 'utf8').replace(/\r\n/g, '\n').split('\n').filter((line) => line.trim());
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
+      if (validateObserverSnapshot(event).ok) events.push(event);
+    } catch { /* corrupt lines never become part of the derived index */ }
+  }
+  return events;
+}
+
+function newer(left, right) {
+  const leftTime = Date.parse(left?.captured_at || '') || 0;
+  const rightTime = Date.parse(right?.captured_at || '') || 0;
+  return leftTime > rightTime || (leftTime === rightTime && String(left?.event_id).localeCompare(String(right?.event_id)) > 0);
+}
+
+export function rebuildObserverIndex(dataDir) {
+  ensureDataDir(dataDir);
+  const byProject = new Map();
+  for (const event of readEvents(dataDir)) {
+    const current = byProject.get(event.project_id);
+    if (!current || newer(event, current.snapshot)) {
+      byProject.set(event.project_id, {
+        projectId: event.project_id,
+        projectName: event.project_name,
+        latestEventId: event.event_id,
+        capturedAt: event.captured_at,
+        snapshot: event,
+        eventCount: 0,
+      });
+    }
+  }
+  for (const event of readEvents(dataDir)) {
+    const item = byProject.get(event.project_id);
+    if (item) item.eventCount += 1;
+  }
+  const index = {
+    schema_version: OBSERVER_DATA_SCHEMA_VERSION,
+    generated_at: new Date().toISOString(),
+    projects: [...byProject.values()].sort((a, b) => a.projectId.localeCompare(b.projectId)),
+  };
+  atomicJson(join(dataDir, OBSERVER_INDEX_FILE), index);
+  return index;
+}
+
+export function readObserverIndex(dataDir) {
+  ensureDataDir(dataDir);
+  const path = join(dataDir, OBSERVER_INDEX_FILE);
+  const index = readJson(path, null);
+  if (index?.schema_version === OBSERVER_DATA_SCHEMA_VERSION && Array.isArray(index.projects)) return index;
+  return rebuildObserverIndex(dataDir);
+}
+
+export function appendObserverEvent(dataDir, event) {
+  ensureDataDir(dataDir);
+  const validation = validateObserverSnapshot(event);
+  if (!validation.ok || validation.size > MAX_SNAPSHOT_BYTES) {
+    return { accepted: false, errors: validation.errors || ['snapshot inválido.'] };
+  }
+  const projects = registeredProjects(dataDir);
+  if (!projects[event.project_id]) {
+    return { accepted: false, errors: [`project_id não registrado: ${event.project_id}`] };
+  }
+  const eventsPath = join(dataDir, OBSERVER_EVENTS_FILE);
+  const existing = readEvents(dataDir).find((item) => item.event_id === event.event_id);
+  if (existing) {
+    if (JSON.stringify(existing) !== JSON.stringify(event)) {
+      return { accepted: false, errors: [`event_id reutilizado com payload diferente: ${event.event_id}`] };
+    }
+    return { accepted: false, duplicate: true, event_id: event.event_id, index: readObserverIndex(dataDir) };
+  }
+  appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, 'utf8');
+  return {
+    accepted: true,
+    duplicate: false,
+    event_id: event.event_id,
+    index: rebuildObserverIndex(dataDir),
+  };
+}
+
+export function getObserverProject(dataDir, projectId) {
+  return readObserverIndex(dataDir).projects.find((project) => project.projectId === projectId) || null;
+}