wendkeep 0.68.6 → 0.70.0

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;
+}

package/src/observer.mjs

@@ -0,0 +1,108 @@
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { appendObserverEvent, readObserverIndex, registerObserverProject } from './observer-store.mjs';
+import { buildProjectSnapshot } from './observer-snapshot.mjs';
+import { startObserverServer } from './observer-server.mjs';
+import { resolveProjectVault } from '../packages/vault/src/project-vault.mjs';
+
+export const OBSERVER_HELP = `wendkeep observer — Observer local multi-projeto
+
+Uso:
+  wendkeep observer serve [--data-dir P] [--host 127.0.0.1] [--port 8787] [--token T]
+                          [--allow-non-loopback]
+  wendkeep observer register --project P [--vault V] [--data-dir D] [--json]
+  wendkeep observer publish --project P [--vault V] [--data-dir D] [--json]
+  wendkeep observer status [--data-dir D] [--json]
+
+O vault continua local e é a fonte oficial. O Observer armazena apenas snapshots sanitizados
+e um índice reconstruível; o container não monta nem copia vaults de projetos.
+`;
+
+function optionValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+function dataDir(argv) {
+  return resolve(optionValue(argv, '--data-dir')
+    || process.env.WENDKEEP_OBSERVER_DATA_DIR
+    || `${homedir()}/.wendkeep-observer`);
+}
+
+function projectRoot(argv) {
+  const value = optionValue(argv, '--project') || process.cwd();
+  return isAbsolute(value) ? resolve(value) : resolve(process.cwd(), value);
+}
+
+function vaultBase(argv, root) {
+  const explicit = optionValue(argv, '--vault');
+  if (explicit) return isAbsolute(explicit) ? resolve(explicit) : resolve(root, explicit);
+  return resolveProjectVault({ startDir: root }).base;
+}
+
+function print(value, asJson) {
+  process.stdout.write(`${asJson ? JSON.stringify(value, null, 2) : String(value)}\n`);
+}
+
+function summary(index) {
+  return {
+    schema_version: index.schema_version,
+    projects: index.projects.map(({ snapshot, ...item }) => item),
+  };
+}
+
+export async function runObserver(argv = []) {
+  const [sub] = argv;
+  const asJson = argv.includes('--json');
+  if (!sub || sub === 'help') {
+    process.stdout.write(OBSERVER_HELP);
+    return 0;
+  }
+  const dir = dataDir(argv);
+
+  if (sub === 'status') {
+    print(summary(readObserverIndex(dir)), asJson);
+    return 0;
+  }
+
+  if (sub === 'serve') {
+    const token = optionValue(argv, '--token') || process.env.WENDKEEP_OBSERVER_TOKEN || '';
+    const host = optionValue(argv, '--host') || '127.0.0.1';
+    const server = await startObserverServer({
+      dataDir: dir,
+      host,
+      port: Number(optionValue(argv, '--port') || 8787),
+      token,
+      allowNonLoopback: argv.includes('--allow-non-loopback'),
+    });
+    if (!token) {
+      await server.close();
+      throw new Error('Observer exige --token ou WENDKEEP_OBSERVER_TOKEN.');
+    }
+    const address = server.address();
+    process.stdout.write(`wendkeep observer listening: http://${address.address}:${address.port}\n`);
+    return 0;
+  }
+
+  if (!['register', 'publish'].includes(sub)) throw new Error(`observer: subcomando desconhecido: ${sub}`);
+  const root = projectRoot(argv);
+  const vault = vaultBase(argv, root);
+  const snapshot = buildProjectSnapshot({ vaultBase: vault, projectRoot: root });
+
+  if (sub === 'register') {
+    const result = registerObserverProject(dir, {
+      projectId: snapshot.project_id,
+      projectName: snapshot.project_name,
+      wendkeepVersion: snapshot.wendkeep_version,
+    });
+    if (!result.registered) throw new Error(result.errors.join(' '));
+    print(result, asJson);
+    return 0;
+  }
+
+  const result = appendObserverEvent(dir, snapshot);
+  if (!result.accepted && !result.duplicate) throw new Error(result.errors.join(' '));
+  print({ ok: true, ...result }, asJson);
+  return 0;
+}

package/src/taxonomy.mjs

@@ -99,6 +99,7 @@ export const HOOK_FILES = [
   'change-guard.mjs',
   'change-nag.mjs',
   'plan-capture.mjs',
+  'observer-publish.mjs',
 ];
 
 // Hook scripts that are safe to invoke directly via `wendkeep hook <name>`.
@@ -122,6 +123,7 @@ export const RUNNABLE_HOOKS = [
   'change-guard',
   'change-nag',
   'plan-capture',
+  'observer-publish',
 ];
 
 // --- companion plugins / MCP --------------------------------------------------