wendkeep 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.25.0] — 2026-07-08
+
+Cost trend/projection + shareable stats + launch assets.
+
+### Added
+- **`wendkeep cost --trend [day|week|month]`** — cost bucketed over time plus a run-rate
+  **projection** (recent-window daily average × horizon). `wendkeep cost --write` generates a
+  `00-Custo.md` trend note in the vault (by-month table + projection + top models). `src/cost.mjs`.
+- **`wendkeep stats`** — one shareable line: sessions · prompts · spend · date span · models
+  (`--json` too). For the npm page, a README badge line, or a post. `src/stats.mjs`.
+- **Launch assets** (`docs/`): README hero (tagline, badges, quickstart, screenshot slot),
+  Show HN / r/ObsidianMD / X post drafts (`docs/20-launch-posts.md`), and a repeatable
+  graph-screenshot guide (`docs/21-graph-screenshot.md`).
+
 ## [0.24.0] — 2026-07-08
 
 ### Changed

package/README.md

@@ -1,9 +1,21 @@
 # wendkeep
 
+> **Your AI coding agent forgets every session. wendkeep makes it remember — in the Obsidian vault you already use.**
+
+[![npm](https://img.shields.io/npm/v/wendkeep.svg)](https://www.npmjs.com/package/wendkeep)
 ![test](https://github.com/rogersialves/wendkeep/actions/workflows/test.yml/badge.svg)
+![zero deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
+![node](https://img.shields.io/badge/node-%E2%89%A518-blue)
 
 **A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code / Codex session is captured turn‑by‑turn into local Markdown — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. On top of that memory core sits a native, zero‑dependency **change lifecycle** (spec → change → TDD → sensor‑gated archive) that keeps intent, work and proof wikilinked in one graph. 100% local, open‑core.
 
+```bash
+npm i -D wendkeep && npx wendkeep init      # captures from the next session on
+npx wendkeep import                          # backfill past Claude + Codex sessions
+```
+
+<!-- SCREENSHOT: Obsidian graph of a wendkeep vault (sessions ↔ decisions ↔ bugs ↔ changes). Drop a PNG/GIF at docs/assets/graph.png and reference it here. -->
+
 > Extracted from a system in daily production use: the capture engine, cost tracking and graph wiring are battle‑tested; the cross‑platform installer (`wendkeep init`) and the native change loop are the newer parts. See [`docs/`](https://github.com/rogersialves/wendkeep/tree/main/docs) for the project's strategy and decision log.
 
 ---

package/bin/wendkeep.mjs

@@ -48,7 +48,9 @@ Usage:
   wendkeep spec <sub>          Living specs: list | show <capability>.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
   wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
-                           --since <date> · --top [N] (priciest sessions) · --json.
+                           --since <date> · --top [N] (priciest) · --trend [day|week|month]
+                           (+ run-rate projection) · --write (generate 00-Custo.md) · --json.
+  wendkeep stats [--vault P]   One shareable line: sessions · prompts · spend · span · models (--json).
   wendkeep import [opts]       Backfill: import this project's past Claude + Codex sessions into
                            the vault (deduped by session_id). --source all|claude|codex (default
                            all) · --stamp-ids (backfill session_id in existing notes) ·
@@ -144,6 +146,11 @@ async function main() {
       runCost(rest);
       break;
     }
+    case 'stats': {
+      const { runStats } = await import('../src/stats.mjs');
+      runStats(rest);
+      break;
+    }
     case 'import': {
       const { runImportCli } = await import('../src/import.mjs');
       runImportCli(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {

package/src/cost.mjs

@@ -1,12 +1,16 @@
 // `wendkeep cost` — aggregate AI-coding spend across every session note in the vault.
 // Each session note carries cost in its frontmatter (main + subagents since 0.10.0); this
 // rolls the whole vault up: total, by day, by model. Pure aggregation + a thin CLI.
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { getLocale } from '../hooks/locale.mjs';
 
 const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
 const usd = (n) => `$${(Number(n) || 0).toFixed(4)}`;
+const today = () => {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+};
 
 function fmValue(content, key) {
   const m = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
@@ -24,6 +28,7 @@ export function parseSessionCost(content) {
     wasted: Number(fmValue(content, 'subagents_wasted_usd')) || 0,
     tokens: Number(fmValue(content, 'tokens_total')) || 0,
     subTokens: Number(fmValue(content, 'subagents_tokens_total')) || 0,
+    prompts: Number(fmValue(content, 'prompts')) || 0,
   };
 }
 
@@ -35,8 +40,9 @@ export function aggregateCosts(entries) {
   let wasted = 0;
   let tokens = 0;
   let subTokens = 0;
+  let prompts = 0;
   for (const e of entries) {
-    main += e.mainCost; sub += e.subCost; wasted += e.wasted || 0; tokens += e.tokens; subTokens += e.subTokens;
+    main += e.mainCost; sub += e.subCost; wasted += e.wasted || 0; tokens += e.tokens; subTokens += e.subTokens; prompts += e.prompts || 0;
     const d = e.date || '?';
     (byDay[d] = byDay[d] || { cost: 0, count: 0 }).cost += e.mainCost + e.subCost;
     byDay[d].count += 1;
@@ -48,12 +54,93 @@ export function aggregateCosts(entries) {
     count: entries.length,
     main: round4(main), sub: round4(sub), total: round4(total), wasted: round4(wasted),
     avg: round4(entries.length ? total / entries.length : 0),
-    tokens, subTokens,
+    tokens, subTokens, prompts,
     byDay: Object.entries(byDay).sort().map(([date, v]) => ({ date, cost: round4(v.cost), count: v.count })),
     byModel: Object.entries(byModel).sort((a, b) => b[1].cost - a[1].cost).map(([model, v]) => ({ model, cost: round4(v.cost), count: v.count })),
   };
 }
 
+// Shift a 'YYYY-MM-DD' string by `delta` days (UTC, pure).
+function shiftDate(dateStr, delta) {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + delta);
+  return d.toISOString().slice(0, 10);
+}
+
+// ISO-ish week key 'YYYY-Www' for a 'YYYY-MM-DD' string (pure).
+function isoWeek(dateStr) {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  const day = (d.getUTCDay() + 6) % 7; // Mon=0
+  d.setUTCDate(d.getUTCDate() - day + 3); // nearest Thursday
+  const firstThu = new Date(Date.UTC(d.getUTCFullYear(), 0, 4));
+  const week = 1 + Math.round(((d - firstThu) / 86400000 - 3 + ((firstThu.getUTCDay() + 6) % 7)) / 7);
+  return `${d.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+
+// Group the per-day cost series (agg.byDay) into day|week|month buckets. Pure.
+export function trendBuckets(byDay, bucket = 'month') {
+  const keyOf = (date) => (bucket === 'day' ? date : bucket === 'week' ? isoWeek(date) : String(date).slice(0, 7));
+  const map = {};
+  for (const d of byDay || []) {
+    if (!d.date || d.date === '?') continue;
+    const k = keyOf(d.date);
+    (map[k] = map[k] || { period: k, cost: 0, count: 0 }).cost += d.cost;
+    map[k].count += d.count;
+  }
+  return Object.values(map).sort((a, b) => a.period.localeCompare(b.period)).map((b) => ({ ...b, cost: round4(b.cost) }));
+}
+
+// Run-rate projection from the last `windowDays` of activity. Pure; nowStr = 'YYYY-MM-DD'
+// (defaults to the latest day seen). Honest: a flat run-rate, not a fitted forecast.
+export function projectSpend(byDay, { nowStr, windowDays = 30, horizonDays = 30 } = {}) {
+  const days = (byDay || []).filter((d) => d.date && d.date !== '?');
+  if (!days.length) return { dailyRate: 0, projected: 0, windowDays, horizonDays, basisDays: 0, basisTotal: 0 };
+  const now = nowStr || days[days.length - 1].date;
+  const cutoff = shiftDate(now, -windowDays);
+  const recent = days.filter((d) => d.date > cutoff);
+  const basisTotal = recent.reduce((s, d) => s + d.cost, 0);
+  const dailyRate = basisTotal / windowDays;
+  return { dailyRate: round4(dailyRate), projected: round4(dailyRate * horizonDays), windowDays, horizonDays, basisDays: recent.length, basisTotal: round4(basisTotal) };
+}
+
+// A generated vault note: cost by month + projection + top models. Overwrites (it is generated).
+export function renderTrendNote(agg, proj, dateStr) {
+  const rows = trendBuckets(agg.byDay, 'month').map((b) => `| ${b.period} | ${usd(b.cost)} | ${b.count} |`).join('\n');
+  const models = agg.byModel.slice(0, 8).map((m) => `| ${m.model} | ${usd(m.cost)} | ${m.count} |`).join('\n');
+  return `---
+type: cost-trend
+date: ${dateStr}
+cssclasses:
+  - topic-dashboard
+tags:
+  - custo
+---
+
+# Custo — tendência
+
+> Gerado por \`wendkeep cost --write\`. ${agg.count} sessão(ões) · total ${usd(agg.total)} · ${usd(agg.avg)}/sessão.
+
+## Por mês
+
+| Mês | Custo | Sessões |
+|---|---|---|
+${rows || '| — | — | — |'}
+
+## Projeção (run-rate ${proj.windowDays}d)
+
+Base: ${usd(proj.basisTotal)} nos últimos ${proj.windowDays} dias (${proj.basisDays} dia(s) com atividade) → **${usd(proj.dailyRate)}/dia**.
+Projeção próximos ${proj.horizonDays} dias: **${usd(proj.projected)}**.
+
+> Run-rate simples (média diária × horizonte), não previsão ajustada.
+
+## Por modelo
+
+| Modelo | Custo | Sessões |
+|---|---|---|
+${models || '| — | — | — |'}
+`;
+}
+
 function walkNotes(dir) {
   const out = [];
   let names;
@@ -111,6 +198,24 @@ export function runCost(argv) {
     process.exit(0);
   }
 
+  const trendIdx = argv.indexOf('--trend');
+  if (trendIdx >= 0) {
+    const bucket = ['day', 'week', 'month'].includes(argv[trendIdx + 1]) ? argv[trendIdx + 1] : 'month';
+    const proj = projectSpend(agg.byDay);
+    process.stdout.write(`Tendência de custo (por ${bucket}):\n`);
+    for (const b of trendBuckets(agg.byDay, bucket)) process.stdout.write(`  ${b.period}  ${usd(b.cost).padStart(11)}  (${b.count})\n`);
+    process.stdout.write(`\nRun-rate ${proj.windowDays}d: ${usd(proj.dailyRate)}/dia · projeção ${proj.horizonDays}d: ${usd(proj.projected)} (base ${usd(proj.basisTotal)} em ${proj.basisDays} dia(s))\n`);
+    process.exit(0);
+  }
+
+  if (argv.includes('--write')) {
+    const proj = projectSpend(agg.byDay);
+    const rel = '00-Custo.md';
+    writeFileSync(join(vaultBase, rel), renderTrendNote(agg, proj, today()), 'utf8');
+    process.stdout.write(`cost --write: ${rel} (nota de tendência gerada)\n`);
+    process.exit(0);
+  }
+
   process.stdout.write(`Custo total (vault): ${usd(agg.total)} — ${agg.count} sessão(ões) · ${usd(agg.avg)}/sessão\n`);
   process.stdout.write(`  main: ${usd(agg.main)} · subagents: ${usd(agg.sub)}\n`);
   if (agg.wasted) process.stdout.write(`  desperdiçado (runs killed/failed): ${usd(agg.wasted)}\n`);

package/src/stats.mjs

@@ -0,0 +1,45 @@
+// `wendkeep stats` — one shareable line about what the vault has captured. For the npm page,
+// a README badge line, or a tweet. Read-only; reuses the cost aggregation.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { collectVaultCost } from './cost.mjs';
+
+const usd = (n) => `$${(Number(n) || 0).toFixed(2)}`;
+const num = (n) => String(Math.round(Number(n) || 0)).replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+
+// Pure: derive the shareable stats from a collectVaultCost aggregate.
+export function statsFrom(agg) {
+  const days = (agg.byDay || []).map((d) => d.date).filter((d) => d && d !== '?').sort();
+  return {
+    sessions: agg.count,
+    prompts: agg.prompts || 0,
+    cost: agg.total,
+    models: (agg.byModel || []).length,
+    firstDay: days[0] || '',
+    lastDay: days[days.length - 1] || '',
+    spanDays: days.length,
+  };
+}
+
+export function statsLine(s) {
+  const span = s.firstDay && s.lastDay ? ` · ${s.spanDays} dia(s) (${s.firstDay}→${s.lastDay})` : '';
+  return `wendkeep: ${num(s.sessions)} sessão(ões) · ${num(s.prompts)} prompts · ${usd(s.cost)} capturado${span} · ${s.models} modelo(s)`;
+}
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+export function runStats(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep stats: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep stats: vault not found: ${vaultBase}\n`); process.exit(2); }
+  const s = statsFrom(collectVaultCost(vaultBase));
+  if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(s, null, 2)}\n`); process.exit(0); }
+  process.stdout.write(`${statsLine(s)}\n`);
+  process.exit(0);
+}