wendkeep 0.2.1 → 0.2.3

package/README.md

@@ -39,6 +39,7 @@ npx wendkeep init
 2. **Merge** the three session hooks and `OBSIDIAN_VAULT_PATH` into `.claude/settings.json` — without clobbering your existing settings (a `.bak` is saved; an unparseable file is left untouched and a `.new` is written for you to merge).
 3. Add the `wendkeep-vault` MCP server to `.mcp.json` (skip with `--no-mcp`).
 4. Offer to pin **companion** plugins/MCP (multi-choice; `context-mode` pre-checked). Each is wired through the most agent-agnostic path it supports — `context-mode` as an `.mcp.json` MCP server (any agent), `understand-anything` via a `understand-inject` SessionStart hook that injects its domain graph when generated, and the Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) as a bonus. Control with `--companions <csv>` or `--no-companions`. (`caveman` additionally runs its own cross-agent installer on non-Claude agents.)
+5. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`.
 
 ```bash
 npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (companions: context-mode)

package/bin/wendkeep.mjs

@@ -32,6 +32,7 @@ Usage:
     --companions <csv>     Companion plugins/MCP to pin: context-mode,caveman,understand-anything
                            (default when interactive/--yes: context-mode).
     --no-companions        Skip companion plugins/MCP entirely.
+    --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
     --yes, -y              Non-interactive; accept defaults.
     --force                Overwrite existing wendkeep config blocks.
 

package/hooks/linked-notes.mjs

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
 import { basename, join } from 'path';
 import {
-  datedFolderRelFromDateStr,
+  monthFolderRelFromDateStr,
   derivedContentKey,
   ensureDir,
   getNextAdrNumber,
@@ -457,7 +457,7 @@ function existingKeysForSession(vaultBase, sessionRel, dateStr) {
   const wikilink = wikilinkFromRel(sessionRel);
   const out = { bugs: [], decisions: [], learnings: [] };
   for (const [type, folder] of Object.entries(DERIVED_FOLDERS)) {
-    const dir = join(vaultBase, datedFolderRelFromDateStr(folder, dateStr));
+    const dir = join(vaultBase, monthFolderRelFromDateStr(folder, dateStr));
     for (const fileName of listMd(dir)) {
       try {
         const c = readFileSync(join(dir, fileName), 'utf-8');
@@ -477,9 +477,9 @@ function alreadyHasKey(keys, candidate) {
 export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options = {}) {
   const linked = { decisions: [], bugs: [], learnings: [] };
   const provider = providerMeta(options.provider);
-  const bugsDir = join(vaultBase, datedFolderRelFromDateStr('05-Bugs', dateStr));
-  const decisionsDir = join(vaultBase, datedFolderRelFromDateStr('04-Decisões', dateStr));
-  const learningsDir = join(vaultBase, datedFolderRelFromDateStr('06-Aprendizados', dateStr));
+  const bugsDir = join(vaultBase, monthFolderRelFromDateStr('05-Bugs', dateStr));
+  const decisionsDir = join(vaultBase, monthFolderRelFromDateStr('04-Decisões', dateStr));
+  const learningsDir = join(vaultBase, monthFolderRelFromDateStr('06-Aprendizados', dateStr));
   ensureDir(bugsDir);
   ensureDir(decisionsDir);
   ensureDir(learningsDir);

package/hooks/obsidian-common.mjs

@@ -133,12 +133,19 @@ export function datedFolderRel(rootFolder, date = new Date()) {
   return join(rootFolder, String(p.year), MONTH_FOLDERS[p.month - 1], `DIA ${pad2(p.day)}`);
 }
 
-// Mesma estrutura datada a partir de uma string 'YYYY-MM-DD' (usada pelas notas derivadas).
+// Mesma estrutura datada a partir de uma string 'YYYY-MM-DD' (sessões: até o DIA).
 export function datedFolderRelFromDateStr(rootFolder, dateStr) {
   const [year, month, day] = String(dateStr).split('-');
   return join(rootFolder, year, MONTH_FOLDERS[Number(month) - 1], `DIA ${pad2(day)}`);
 }
 
+// Estrutura até o MÊS (sem DIA) — usada pelas notas derivadas (decisões/bugs/
+// aprendizados): tudo do mês fica junto em <pasta>/<ano>/<MM-MMM>/.
+export function monthFolderRelFromDateStr(rootFolder, dateStr) {
+  const [year, month] = String(dateStr).split('-');
+  return join(rootFolder, year, MONTH_FOLDERS[Number(month) - 1]);
+}
+
 export function sessionFolderRel(date = new Date()) {
   return datedFolderRel('02-Sessões', date);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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": {

package/src/init.mjs

@@ -3,7 +3,8 @@
 // OBSIDIAN_VAULT_PATH into .claude/settings.json, and adds the mcpvault server to
 // .mcp.json. Idempotent: re-running only adds what is missing.
 import { spawnSync } from 'node:child_process';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { basename, isAbsolute, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import {
@@ -19,9 +20,17 @@ import {
   companionMcpPatch,
   companionHookSpecs,
   cavemanInstallerCommand,
+  cavemanInstallerUrl,
 } from './taxonomy.mjs';
 import { renderVaultReadme } from './vault-readme.mjs';
 import { canInteractiveSelect, selectCompanionsInteractive } from './companion-select.mjs';
+import {
+  SNIPPET_NAME,
+  renderColorSnippetCss,
+  mergeAppearance,
+  graphColorGroups,
+  mergeGraphColorGroups,
+} from './vault-theme.mjs';
 
 function parseArgs(argv) {
   const args = { mcp: true, yes: false, force: false };
@@ -33,6 +42,7 @@ function parseArgs(argv) {
     else if (a === '--yes' || a === '-y') args.yes = true;
     else if (a === '--force') args.force = true;
     else if (a === '--no-companions') args.noCompanions = true;
+    else if (a === '--no-colors') args.noColors = true;
     else if (a === '--companions') args.companions = argv[++i];
     else if (a.startsWith('--companions=')) args.companions = a.slice(13);
     else if (a.startsWith('--vault=')) args.vault = a.slice(8);
@@ -118,6 +128,60 @@ export function mergeMcp(existing, { vaultPath, withVault = true, companions = [
   return m;
 }
 
+// Run caveman's cross-agent installer (non-Claude skill coverage). Downloads the
+// script to a temp file and runs it as a FILE — piping to iex/bash leaves the
+// script's self-path null and the installer aborts. Best-effort, fail-soft: the
+// Claude Code plugin entry is already wired regardless.
+async function runCavemanInstaller(log) {
+  const url = cavemanInstallerUrl();
+  const ext = process.platform === 'win32' ? 'ps1' : 'sh';
+  const tmp = join(tmpdir(), `wendkeep-caveman-install-${process.pid}.${ext}`);
+  log(`\n  caveman: fetching cross-agent installer (best-effort): ${url}`);
+  try {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    writeFileSync(tmp, await res.text(), 'utf8');
+    const cmd = cavemanInstallerCommand(process.platform, tmp);
+    log(`  caveman: running ${cmd.command} ${cmd.args.join(' ')}`);
+    const r = spawnSync(cmd.command, cmd.args, { stdio: 'inherit' });
+    if (r.status !== 0) {
+      log(`  [!] caveman installer exited ${r.status ?? '?'} — Claude Code plugin entry still wired; rerun manually if needed.`);
+    }
+  } catch (e) {
+    log(`  [!] caveman installer skipped (${e.message}) — Claude Code plugin entry still wired.`);
+  } finally {
+    try { rmSync(tmp, { force: true }); } catch { /* temp cleanup best-effort */ }
+  }
+}
+
+// Install the vault color system into .obsidian: write wendkeep's CSS snippet,
+// enable it (non-destructive), and add graph color groups. Returns a short note.
+// Unparseable user JSON is left untouched (we only merge into valid/absent files).
+function installVaultColors(vaultPath) {
+  const obsidianDir = join(vaultPath, '.obsidian');
+  const snippetsDir = join(obsidianDir, 'snippets');
+  mkdirSync(snippetsDir, { recursive: true });
+  writeFileSync(join(snippetsDir, `${SNIPPET_NAME}.css`), renderColorSnippetCss(), 'utf8');
+
+  let enabled = false;
+  const appPath = join(obsidianDir, 'appearance.json');
+  const appRead = readJsonSafe(appPath);
+  if (appRead.ok) {
+    writeJson(appPath, mergeAppearance(appRead.data || {}, SNIPPET_NAME));
+    enabled = true;
+  }
+
+  let groups = 0;
+  const graphPath = join(obsidianDir, 'graph.json');
+  const graphRead = readJsonSafe(graphPath);
+  if (graphRead.ok) {
+    const merged = mergeGraphColorGroups(graphRead.data || {}, graphColorGroups());
+    writeJson(graphPath, merged);
+    groups = graphColorGroups().length;
+  }
+  return `snippet ${SNIPPET_NAME}.css${enabled ? ' (enabled)' : ' (enable by hand: appearance.json unreadable)'} + ${groups} graph group(s)`;
+}
+
 // --- main -------------------------------------------------------------------
 
 export async function runInit(argv) {
@@ -148,11 +212,12 @@ export async function runInit(argv) {
   } else if (args.companions !== undefined) {
     companions = resolveCompanions({ companionsFlag: args.companions });
   } else if (process.stdin.isTTY && !args.yes) {
-    log('\nCompanions (plugins/MCP opcionais — context-mode é a principal):');
     if (canInteractiveSelect()) {
+      log(''); // the checkbox menu renders its own header
       companions = await selectCompanionsInteractive(COMPANIONS);
     } else {
       // Text fallback (no raw-mode TTY): list + comma input with clear instructions.
+      log('\nCompanions (plugins/MCP opcionais — context-mode é a principal):');
       for (const c of COMPANIONS) log(`  ${c.default ? '[x]' : '[ ]'} ${c.label}`);
       const def = resolveCompanions({}).join(',');
       const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -170,7 +235,8 @@ export async function runInit(argv) {
   log(`  project    : ${projectPath}`);
   log(`  vault      : ${vaultPath}`);
   log(`  mcp        : ${args.mcp ? 'mcpvault (wendkeep-vault)' : 'skipped'}`);
-  log(`  companions : ${companions.length ? companions.join(', ') : 'none'}\n`);
+  log(`  companions : ${companions.length ? companions.join(', ') : 'none'}`);
+  log(`  colors     : ${args.noColors ? 'skipped' : 'wendkeep-colors (snippet + graph groups)'}\n`);
 
   // 1. Vault taxonomy ---------------------------------------------------------
   if (!existsSync(vaultPath)) mkdirSync(vaultPath, { recursive: true });
@@ -189,7 +255,7 @@ export async function runInit(argv) {
     writeFileSync(readmePath, renderVaultReadme({ projectName: basename(projectPath), vaultPath, withMcp: args.mcp }), 'utf8');
     readmeNote = ', README.md created';
   }
-  log(`  [1/3] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)${readmeNote}`);
+  log(`  [1/4] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)${readmeNote}`);
 
   // 2. .claude/settings.json --------------------------------------------------
   const settingsPath = join(projectPath, '.claude', 'settings.json');
@@ -198,13 +264,13 @@ export async function runInit(argv) {
     // Unparseable existing file — never clobber. Drop a .new for manual merge.
     const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions }).settings;
     writeJson(`${settingsPath}.new`, fresh);
-    log(`  [2/3] settings.json exists but is not valid JSON -> wrote ${settingsPath}.new (merge by hand)`);
+    log(`  [2/4] 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, companions });
     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' : ''})`);
+    log(`  [2/4] settings.json ${hadFile ? 'merged' : 'created'} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${hadFile ? ', .bak saved' : ''})`);
   }
 
   // 3. .mcp.json --------------------------------------------------------------
@@ -217,32 +283,28 @@ export async function runInit(argv) {
     const names = [args.mcp && MCP_SERVER_KEY, ...Object.keys(companionMcp)].filter(Boolean).join(', ');
     if (!mcpRead.ok) {
       writeJson(`${mcpPath}.new`, mergeMcp(null, mcpOpts));
-      log(`  [3/3] .mcp.json exists but is not valid JSON -> wrote ${mcpPath}.new (merge by hand)`);
+      log(`  [3/4] .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, mcpOpts));
-      log(`  [3/3] .mcp.json ${hadFile ? 'merged' : 'created'} (${names}${hadFile ? ', .bak saved' : ''})`);
+      log(`  [3/4] .mcp.json ${hadFile ? 'merged' : 'created'} (${names}${hadFile ? ', .bak saved' : ''})`);
     }
   } else {
-    log('  [3/3] .mcp.json skipped (--no-mcp, no MCP companions)');
+    log('  [3/4] .mcp.json skipped (--no-mcp, no MCP companions)');
+  }
+
+  // 4. Vault color system (.obsidian) -----------------------------------------
+  if (args.noColors) {
+    log('  [4/4] colors skipped (--no-colors)');
+  } else {
+    log(`  [4/4] colors: ${installVaultColors(vaultPath)}`);
   }
 
   // caveman has no MCP / agnostic-hook path: on non-Claude agents its skills come
   // from its own cross-agent installer. Best-effort, fail-soft — the Claude Code
   // plugin entry is already wired in settings.json regardless.
-  if (companions.includes('caveman')) {
-    const cmd = cavemanInstallerCommand();
-    log(`\n  caveman: running cross-agent installer (best-effort): ${cmd.command} ${cmd.args.join(' ')}`);
-    try {
-      const r = spawnSync(cmd.command, cmd.args, { stdio: 'inherit' });
-      if (r.status !== 0) {
-        log(`  [!] caveman installer exited ${r.status ?? '?'} — Claude Code plugin entry still wired; rerun manually if needed.`);
-      }
-    } catch (e) {
-      log(`  [!] caveman installer could not run (${e.code || e.message}) — Claude Code plugin entry still wired.`);
-    }
-  }
+  if (companions.includes('caveman')) await runCavemanInstaller(log);
 
   log('\nNext steps:');
   log(`  1. Open the vault in Obsidian: "Open folder as vault" -> ${vaultPath}`);

package/src/taxonomy.mjs

@@ -178,15 +178,21 @@ export function companionHookSpecs(ids) {
   return specs;
 }
 
-// Build the platform-appropriate command to run caveman's own cross-agent installer
-// (used on non-Claude agents — caveman has no MCP/agnostic-hook path). Pure: returns
-// {command, args}; the caller decides whether to spawn it.
-export function cavemanInstallerCommand(platform = process.platform) {
+// The caveman installer URL for this platform (.ps1 on Windows, .sh elsewhere).
+export function cavemanInstallerUrl(platform = process.platform) {
   const { sh, ps1 } = COMPANION_BY_ID.caveman.installer;
+  return platform === 'win32' ? ps1 : sh;
+}
+
+// Command to run caveman's installer FROM A LOCAL FILE. We download the script to a
+// temp file and run it as a file (not `irm|iex` / `curl|bash`) so the script gets a
+// real $PSCommandPath/$0 — piping to iex leaves that null and the installer aborts
+// ("cannot bind argument to parameter 'Path'"). Pure: returns {command, args}.
+export function cavemanInstallerCommand(platform = process.platform, scriptPath) {
   if (platform === 'win32') {
-    return { command: 'powershell', args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', `irm ${ps1} | iex`] };
+    return { command: 'powershell', args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath] };
   }
-  return { command: 'bash', args: ['-c', `curl -fsSL ${sh} | bash`] };
+  return { command: 'bash', args: [scriptPath] };
 }
 
 // Derive the default vault folder name from the project folder: `.<project>-vault`.

package/src/vault-theme.mjs

@@ -0,0 +1,75 @@
+// Vault color system for `wendkeep init`. Two layers, both keyed to the note
+// taxonomy the hooks already emit:
+//   - a CSS snippet that accents an open note by its `cssclasses`
+//     (topic-session/decision/bug/learning), enabled via appearance.json
+//   - Obsidian graph color groups that tint nodes by their folder
+// Pure + side-effect free; init does the file I/O and non-destructive merges.
+
+export const SNIPPET_NAME = 'wendkeep-colors';
+
+// Soft, semantic palette — readable in light and dark themes.
+export const NOTE_COLORS = {
+  session: { cssClass: 'topic-session', folder: '02-Sessões', hex: '#4f86c6' }, // blue
+  decision: { cssClass: 'topic-decision', folder: '04-Decisões', hex: '#9b72cf' }, // purple
+  bug: { cssClass: 'topic-bug', folder: '05-Bugs', hex: '#d9645c' }, // red
+  learning: { cssClass: 'topic-learning', folder: '06-Aprendizados', hex: '#5ca862' }, // green
+};
+
+const ENTRIES = Object.entries(NOTE_COLORS);
+
+export function renderColorSnippetCss() {
+  const vars = ENTRIES.map(([k, v]) => `  --wk-${k}: ${v.hex};`).join('\n');
+  const blocks = ENTRIES.map(([k, v]) => {
+    const c = `var(--wk-${k})`;
+    return [
+      `/* ${k} */`,
+      `.${v.cssClass} .inline-title {`,
+      `  color: ${c};`,
+      `  border-left: 4px solid ${c};`,
+      `  padding-left: 0.5em;`,
+      `}`,
+      `.${v.cssClass} .view-header-title { color: ${c}; }`,
+      `.${v.cssClass} .markdown-preview-view h1 { border-bottom: 2px solid ${c}; }`,
+    ].join('\n');
+  }).join('\n\n');
+
+  return `/* ${SNIPPET_NAME} — generated by wendkeep. Accents notes by type (cssclasses). */
+:root {
+${vars}
+}
+
+${blocks}
+`;
+}
+
+// Add the snippet to appearance.json's enabled list without touching other prefs.
+export function mergeAppearance(existing, snippetName = SNIPPET_NAME) {
+  const a = existing && typeof existing === 'object' ? { ...existing } : {};
+  const set = new Set(Array.isArray(a.enabledCssSnippets) ? a.enabledCssSnippets : []);
+  set.add(snippetName);
+  a.enabledCssSnippets = [...set];
+  return a;
+}
+
+// Graph color groups: one per note folder, colored from the palette.
+export function graphColorGroups() {
+  return ENTRIES.map(([, v]) => ({
+    query: `path:"${v.folder}"`,
+    color: { a: 1, rgb: parseInt(v.hex.slice(1), 16) },
+  }));
+}
+
+// Merge color groups into graph.json, deduping by query and keeping other keys.
+export function mergeGraphColorGroups(existing, groups) {
+  const g = existing && typeof existing === 'object' ? { ...existing } : {};
+  const current = Array.isArray(g.colorGroups) ? [...g.colorGroups] : [];
+  const seen = new Set(current.map((x) => x.query));
+  for (const group of groups) {
+    if (!seen.has(group.query)) {
+      current.push(group);
+      seen.add(group.query);
+    }
+  }
+  g.colorGroups = current;
+  return g;
+}