wendkeep 0.1.0

package/hooks/vault-health.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import {
+  controlPath,
+  getVaultBase,
+  listMarkdownFiles,
+  readControl,
+  readSessionRegistry,
+  wikilinkFromRel,
+} from './obsidian-common.mjs';
+
+const DEFAULT_PENDING_PATTERNS = [
+  /^- \[ \] Revisar resumo da sessão$/i,
+  /^- \[ \] Verificar se houve decisões a registrar$/i,
+  /^- \[ \] Verificar se houve bugs a registrar$/i,
+  /^- \[ \] Verificar se houve aprendizados a registrar$/i,
+];
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (!item.startsWith('--')) continue;
+    const key = item.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function findDuplicateTurnMarkers(content) {
+  const seen = new Set();
+  const duplicated = new Set();
+  const regex = /<!-- codex-turn: ([^>]+) -->/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const turnId = match[1].trim();
+    if (seen.has(turnId)) duplicated.add(turnId);
+    seen.add(turnId);
+  }
+  return [...duplicated];
+}
+
+function hasHeadingAfterClosing(content) {
+  const closing = content.indexOf('\n## Encerramento');
+  if (closing === -1) return false;
+  return /\n#{2,3} /.test(content.slice(closing + '\n## Encerramento'.length));
+}
+
+function sectionBody(content, heading) {
+  const marker = `\n## ${heading}\n`;
+  const start = content.indexOf(marker);
+  if (start === -1) return '';
+  const bodyStart = start + marker.length;
+  const next = content.slice(bodyStart).search(/\n## /);
+  const bodyEnd = next === -1 ? content.length : bodyStart + next;
+  return content.slice(bodyStart, bodyEnd);
+}
+
+function hasDefaultPending(content) {
+  return sectionBody(content, 'Pendências')
+    .split('\n')
+    .some((line) => DEFAULT_PENDING_PATTERNS.some((pattern) => pattern.test(line.trim())));
+}
+
+function usageSectionIsPlaced(content) {
+  const usage = content.indexOf('\n## Uso de tokens e custos');
+  if (usage === -1) return true;
+  const changed = content.indexOf('\n## Arquivos criados ou alterados');
+  const pending = content.indexOf('\n## Pendências');
+  const closing = content.indexOf('\n## Encerramento');
+  if (pending === -1 || closing === -1) return false;
+  return usage < pending && usage < closing && (changed === -1 || usage > changed);
+}
+
+function linkedNotesFromSession(content) {
+  const notes = [];
+  const regex = /\[\[((?:04-Decisões|05-Bugs|06-Aprendizados)\/[^\]]+)\]\]/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    if (!notes.includes(match[1])) notes.push(match[1]);
+  }
+  return notes;
+}
+
+function checkSession({ vaultBase, sessionRel, control, registry }) {
+  const failures = [];
+  const warnings = [];
+  const metrics = {};
+  const sessionPath = join(vaultBase, sessionRel);
+
+  if (!existsSync(sessionPath)) {
+    failures.push(`Sessão não encontrada: ${sessionRel}`);
+    return { failures, warnings, metrics };
+  }
+
+  const content = readFileSync(sessionPath, 'utf-8');
+  const duplicates = findDuplicateTurnMarkers(content);
+  metrics.turnMarkers = (content.match(/<!-- codex-turn:/g) || []).length;
+  metrics.duplicateTurnMarkers = duplicates.length;
+
+  if (duplicates.length) failures.push(`Marcadores codex-turn duplicados: ${duplicates.join(', ')}`);
+  if (hasHeadingAfterClosing(content)) failures.push('Há headings/iterações após ## Encerramento.');
+  if (!usageSectionIsPlaced(content)) failures.push('## Uso de tokens e custos está fora da posição esperada.');
+  if (hasDefaultPending(content)) warnings.push('Pendências ainda contém placeholders padrão.');
+
+  const registryEntry = registry.sessions?.[control.session_id];
+  if (control.session_id && !registryEntry) {
+    failures.push(`SESSION_REGISTRY não possui session_id ativo: ${control.session_id}`);
+  } else if (registryEntry) {
+    if (registryEntry.session_file !== sessionRel) {
+      failures.push('SESSION_REGISTRY diverge do CURRENT_SESSION.md para a sessão ativa.');
+    }
+    if (!registryEntry.transcript_path) {
+      warnings.push('SESSION_REGISTRY não possui transcript_path para a sessão ativa.');
+    } else if (!existsSync(registryEntry.transcript_path)) {
+      warnings.push(`Transcript da sessão ativa não encontrado: ${registryEntry.transcript_path}`);
+    }
+  }
+
+  const sessionLink = wikilinkFromRel(sessionRel);
+  for (const noteRel of linkedNotesFromSession(content)) {
+    const notePath = join(vaultBase, noteRel.endsWith('.md') ? noteRel : `${noteRel}.md`);
+    if (!existsSync(notePath)) {
+      failures.push(`Nota derivada linkada não existe: ${noteRel}`);
+      continue;
+    }
+    const noteContent = readFileSync(notePath, 'utf-8');
+    if (!noteContent.includes(sessionLink) && !noteContent.includes(sessionRel)) {
+      failures.push(`Nota derivada sem backlink para a sessão: ${noteRel}`);
+    }
+  }
+
+  return { failures, warnings, metrics };
+}
+
+export function runVaultHealth({ vaultBase, session = '' }) {
+  const control = readControl(vaultBase);
+  const registry = readSessionRegistry(vaultBase);
+  const sessionRel = session || control.session_file || control.last_session_file || '';
+  const failures = [];
+  const warnings = [];
+
+  if (!existsSync(controlPath(vaultBase))) {
+    failures.push('CURRENT_SESSION.md não encontrado.');
+  }
+  if (!sessionRel) failures.push('Nenhuma sessão ativa ou última sessão encontrada no controle.');
+
+  const sessionResult = sessionRel
+    ? checkSession({ vaultBase, sessionRel, control, registry })
+    : { failures: [], warnings: [], metrics: {} };
+  failures.push(...sessionResult.failures);
+  warnings.push(...sessionResult.warnings);
+
+  const staleDone = Object.values(registry.sessions || {})
+    .filter((item) => item.status === 'active' && item.ended_at)
+    .length;
+  if (staleDone) warnings.push(`${staleDone} entradas active com ended_at no SESSION_REGISTRY.`);
+
+  const derivedFolders = ['04-Decisões', '05-Bugs', '06-Aprendizados'];
+  const derivedCount = derivedFolders.reduce((total, folder) => {
+    const dir = join(vaultBase, folder);
+    return total + (existsSync(dir) ? listMarkdownFiles(dir).length : 0);
+  }, 0);
+
+  return {
+    ok: failures.length === 0,
+    session: sessionRel,
+    failures,
+    warnings,
+    metrics: {
+      ...sessionResult.metrics,
+      registrySessions: Object.keys(registry.sessions || {}).length,
+      derivedNotes: derivedCount,
+    },
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const vaultBase = getVaultBase({ obsidian_vault_path: args.vault });
+  const result = runVaultHealth({ vaultBase, session: args.session || '' });
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.ok) process.exitCode = 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    main();
+  } catch (error) {
+    process.stderr.write(`[codex-obsidian] Vault health falhou: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "wendkeep",
+  "version": "0.1.0",
+  "description": "Automatically capture AI coding agent sessions (Claude Code, Codex) as local Markdown in your Obsidian vault — turn-by-turn history, cost/token tracking, auto-extracted decisions/bugs/learnings, rendered in the graph. Local-first.",
+  "type": "module",
+  "bin": {
+    "wendkeep": "bin/wendkeep.mjs",
+    "wk": "bin/wendkeep.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "hooks",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "check": "node --check bin/wendkeep.mjs && node --check src/init.mjs && node --check src/doctor.mjs"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "obsidian",
+    "session-memory",
+    "ai-agent",
+    "markdown",
+    "local-first",
+    "knowledge-graph",
+    "token-cost"
+  ],
+  "author": "Roger Alves",
+  "license": "MIT"
+}

package/src/doctor.mjs

@@ -0,0 +1,36 @@
+// `wendkeep doctor` — run the bundled vault-health check against a vault.
+// Resolves the vault from --vault or the OBSIDIAN_VAULT_PATH env var, then runs
+// hooks/vault-health.mjs (which reads getVaultBase()).
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function runDoctor(argv) {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const hookFile = join(here, '..', 'hooks', 'vault-health.mjs');
+  if (!existsSync(hookFile)) {
+    process.stderr.write(`wendkeep doctor: vault-health.mjs not found at ${hookFile}\n`);
+    process.exit(2);
+  }
+
+  let vault;
+  const passthrough = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--vault') vault = argv[++i];
+    else if (a.startsWith('--vault=')) vault = a.slice(8);
+    else passthrough.push(a);
+  }
+
+  const env = { ...process.env };
+  if (vault) env.OBSIDIAN_VAULT_PATH = isAbsolute(vault) ? vault : resolve(process.cwd(), vault);
+
+  if (!env.OBSIDIAN_VAULT_PATH) {
+    process.stderr.write('wendkeep doctor: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+    process.exit(2);
+  }
+
+  const r = spawnSync(process.execPath, [hookFile, ...passthrough], { stdio: 'inherit', env });
+  process.exit(r.status ?? 0);
+}

package/src/init.mjs

@@ -0,0 +1,171 @@
+// `wendkeep init` — cross-platform replacement for setup-vault.ps1.
+// Creates the vault taxonomy, NON-DESTRUCTIVELY merges the session hooks +
+// OBSIDIAN_VAULT_PATH into .claude/settings.json, and adds the mcpvault server to
+// .mcp.json. Idempotent: re-running only adds what is missing.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import {
+  VAULT_FOLDERS,
+  SESSION_HOOKS,
+  MCP_SERVER_KEY,
+  mcpServerEntry,
+  hookCommand,
+} from './taxonomy.mjs';
+
+function parseArgs(argv) {
+  const args = { mcp: true, yes: false, force: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--vault') args.vault = argv[++i];
+    else if (a === '--project') args.project = argv[++i];
+    else if (a === '--no-mcp') args.mcp = false;
+    else if (a === '--yes' || a === '-y') args.yes = true;
+    else if (a === '--force') args.force = true;
+    else if (a.startsWith('--vault=')) args.vault = a.slice(8);
+    else if (a.startsWith('--project=')) args.project = a.slice(10);
+  }
+  return args;
+}
+
+function readJsonSafe(path) {
+  // Returns { ok, data }. ok=false means the file exists but is not parseable —
+  // caller must NOT clobber it (we write a *.new beside it instead).
+  if (!existsSync(path)) return { ok: true, data: null };
+  try {
+    return { ok: true, data: JSON.parse(readFileSync(path, 'utf8')) };
+  } catch {
+    return { ok: false, data: null };
+  }
+}
+
+function writeJson(path, obj) {
+  ensureParent(path);
+  writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
+}
+
+function ensureParent(path) {
+  const dir = resolve(path, '..');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function backup(path) {
+  const bak = `${path}.bak`;
+  if (!existsSync(bak)) copyFileSync(path, bak);
+  return bak;
+}
+
+// --- merges -----------------------------------------------------------------
+
+function mergeSettings(existing, { vaultPath, withMcp, force }) {
+  const s = existing && typeof existing === 'object' ? { ...existing } : {};
+  s.hooks = { ...(s.hooks || {}) };
+  let added = 0;
+  for (const h of SESSION_HOOKS) {
+    const command = hookCommand(h.name);
+    const groups = Array.isArray(s.hooks[h.event]) ? [...s.hooks[h.event]] : [];
+    const present = groups.some((g) => (g.hooks || []).some((x) => x.command === command));
+    if (present && !force) {
+      s.hooks[h.event] = groups;
+      continue;
+    }
+    const entry = { type: 'command', command, timeout: h.timeout, statusMessage: h.statusMessage };
+    const group = h.matcher ? { matcher: h.matcher, hooks: [entry] } : { hooks: [entry] };
+    groups.push(group);
+    s.hooks[h.event] = groups;
+    added += 1;
+  }
+  s.env = { ...(s.env || {}), OBSIDIAN_VAULT_PATH: vaultPath };
+  if (withMcp) {
+    const set = new Set(Array.isArray(s.enabledMcpjsonServers) ? s.enabledMcpjsonServers : []);
+    set.add(MCP_SERVER_KEY);
+    s.enabledMcpjsonServers = [...set];
+  }
+  return { settings: s, added };
+}
+
+function mergeMcp(existing, vaultPath) {
+  const m = existing && typeof existing === 'object' ? { ...existing } : {};
+  m.mcpServers = { ...(m.mcpServers || {}) };
+  m.mcpServers[MCP_SERVER_KEY] = mcpServerEntry(vaultPath);
+  return m;
+}
+
+// --- main -------------------------------------------------------------------
+
+export async function runInit(argv) {
+  const args = parseArgs(argv);
+  const projectPath = resolve(args.project || process.cwd());
+  const log = (s) => process.stdout.write(`${s}\n`);
+
+  let vaultPath = args.vault;
+  if (!vaultPath) {
+    const fallback = join(projectPath, '.wendkeep-vault');
+    if (process.stdin.isTTY && !args.yes) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const ans = (await rl.question(`Obsidian vault path [${fallback}]: `)).trim();
+      rl.close();
+      vaultPath = ans || fallback;
+    } else {
+      vaultPath = fallback;
+    }
+  }
+  vaultPath = isAbsolute(vaultPath) ? vaultPath : resolve(projectPath, vaultPath);
+
+  log('\nwendkeep init');
+  log(`  project : ${projectPath}`);
+  log(`  vault   : ${vaultPath}`);
+  log(`  mcp     : ${args.mcp ? 'mcpvault (wendkeep-vault)' : 'skipped'}\n`);
+
+  // 1. Vault taxonomy ---------------------------------------------------------
+  if (!existsSync(vaultPath)) mkdirSync(vaultPath, { recursive: true });
+  let created = 0;
+  for (const f of VAULT_FOLDERS) {
+    const p = join(vaultPath, f);
+    if (!existsSync(p)) {
+      mkdirSync(p, { recursive: true });
+      created += 1;
+    }
+  }
+  log(`  [1/3] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)`);
+
+  // 2. .claude/settings.json --------------------------------------------------
+  const settingsPath = join(projectPath, '.claude', 'settings.json');
+  const settingsRead = readJsonSafe(settingsPath);
+  if (!settingsRead.ok) {
+    // Unparseable existing file — never clobber. Drop a .new for manual merge.
+    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true }).settings;
+    writeJson(`${settingsPath}.new`, fresh);
+    log(`  [2/3] settings.json exists but is not valid JSON -> wrote ${settingsPath}.new (merge by hand)`);
+  } else {
+    const hadFile = settingsRead.data !== null;
+    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force });
+    if (hadFile) backup(settingsPath);
+    writeJson(settingsPath, settings);
+    log(`  [2/3] settings.json ${hadFile ? 'merged' : 'created'} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${hadFile ? ', .bak saved' : ''})`);
+  }
+
+  // 3. .mcp.json --------------------------------------------------------------
+  if (args.mcp) {
+    const mcpPath = join(projectPath, '.mcp.json');
+    const mcpRead = readJsonSafe(mcpPath);
+    if (!mcpRead.ok) {
+      writeJson(`${mcpPath}.new`, mergeMcp(null, vaultPath));
+      log(`  [3/3] .mcp.json exists but is not valid JSON -> wrote ${mcpPath}.new (merge by hand)`);
+    } else {
+      const hadFile = mcpRead.data !== null;
+      if (hadFile) backup(mcpPath);
+      writeJson(mcpPath, mergeMcp(mcpRead.data, vaultPath));
+      log(`  [3/3] .mcp.json ${hadFile ? 'merged' : 'created'} (wendkeep-vault server${hadFile ? ', .bak saved' : ''})`);
+    }
+  } else {
+    log('  [3/3] .mcp.json skipped (--no-mcp)');
+  }
+
+  log('\nNext steps:');
+  log(`  1. Open the vault in Obsidian: "Open folder as vault" -> ${vaultPath}`);
+  log('  2. Make sure wendkeep is installed where the agent runs (npm i -D wendkeep, or -g).');
+  log('  3. Open Claude Code in this project and send a test prompt.');
+  log('  4. Confirm a note appears under 02-Sessões/<year>/<month>/DIA <dd>/ in the vault.');
+  log('  Update later with: npm update wendkeep  (no re-copying — hooks live in the package).\n');
+}

package/src/taxonomy.mjs

@@ -0,0 +1,76 @@
+// Shared, data-only constants for the wendkeep installer and CLI.
+// Kept free of side effects so both bin/ and src/ can import it cheaply.
+
+// Vault folder taxonomy the hooks read from / write to.
+// NOTE: folder names are currently Portuguese (the convention the hooks hardcode
+// in obsidian-common.mjs: sessionFolderRel -> '02-Sessões', derived notes ->
+// '04-Decisões' / '05-Bugs' / '06-Aprendizados'). Internationalizing these is
+// tracked as a known limitation in the README — do not rename here without also
+// changing the hooks.
+export const VAULT_FOLDERS = [
+  '00-Inbox',
+  '01-Projeto',
+  '02-Sessões',
+  '03-Linear',
+  '04-Decisões',
+  '05-Bugs',
+  '06-Aprendizados',
+  'Templates',
+  '.brain',
+];
+
+// Every file that must travel together for the hooks to run (shared lib +
+// entrypoints + price table). Mirrors the list the old setup-vault.ps1 copied.
+export const HOOK_FILES = [
+  'obsidian-common.mjs',
+  'session-start.mjs',
+  'session-ensure.mjs',
+  'session-stop.mjs',
+  'linked-notes.mjs',
+  'token-usage.mjs',
+  'pricing.json',
+  'brain-core.mjs',
+  'brain-inject.mjs',
+  'brain-recall.mjs',
+  'brain-reindex.mjs',
+  'session-backfill.mjs',
+  'vault-health.mjs',
+];
+
+// Hook scripts that are safe to invoke directly via `wendkeep hook <name>`.
+// (Excludes pure libraries like obsidian-common / linked-notes / token-usage /
+// brain-core, which are imported by the entrypoints rather than run standalone.)
+export const RUNNABLE_HOOKS = [
+  'session-start',
+  'session-ensure',
+  'session-stop',
+  'session-backfill',
+  'brain-inject',
+  'brain-recall',
+  'brain-reindex',
+  'vault-health',
+];
+
+// The MCP server entry wendkeep wires into .mcp.json so the agent can read/write the
+// vault. Uses the published mcpvault server (no secrets).
+export function mcpServerEntry(vaultPath) {
+  return {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', '@bitbonsai/mcpvault@latest', vaultPath],
+  };
+}
+export const MCP_SERVER_KEY = 'wendkeep-vault';
+
+// The three Claude Code session hooks, expressed as `wendkeep hook <name>` so the
+// installed package is the single source of truth (update with `npm update wendkeep`,
+// no re-copying). Returned as a spec the merge logic folds into settings.json.
+export const SESSION_HOOKS = [
+  { event: 'SessionStart', matcher: 'startup', name: 'session-start', timeout: 30, statusMessage: 'wendkeep: opening Obsidian session' },
+  { event: 'Stop', matcher: null, name: 'session-stop', timeout: 60, statusMessage: 'wendkeep: writing session checkpoint' },
+  { event: 'UserPromptSubmit', matcher: null, name: 'session-ensure', timeout: 30, statusMessage: 'wendkeep: ensuring active session' },
+];
+
+export function hookCommand(name) {
+  return `npx wendkeep hook ${name}`;
+}