claudenv 1.2.5 → 1.3.0

package/src/doctor.js

@@ -0,0 +1,175 @@
+/**
+ * CLI: `claudenv doctor` — health-check the claudenv setup.
+ *
+ * Prints a compact OK / WARN / FAIL line per check; exits 0 if no FAILs.
+ */
+
+import { stat, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+import {
+  claudenvHome,
+  memoriesDir,
+  globalDecisionsDir,
+  indexMdPath,
+} from './memory-paths.js';
+
+const OK = '[OK]  ';
+const WARN = '[WARN]';
+const FAIL = '[FAIL]';
+
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function nodeVersionCheck() {
+  const major = parseInt(process.version.slice(1).split('.')[0], 10);
+  if (major >= 20) return { status: OK, msg: `Node.js ${process.version}` };
+  return { status: FAIL, msg: `Node.js ${process.version} — require >= 20` };
+}
+
+async function claudeCliCheck() {
+  try {
+    const out = execSync('claude --version', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return { status: OK, msg: `claude CLI: ${out}` };
+  } catch {
+    // WARN, not FAIL — claude CLI is only required for `claudenv loop`.
+    // memory / decisions / canon CLI work fine without it. FAIL'ing here
+    // would also break `claudenv doctor` in CI environments where claude
+    // isn't installed.
+    return {
+      status: WARN,
+      msg: 'claude CLI not found — required for `claudenv loop`. Install from https://docs.anthropic.com/en/docs/claude-code',
+    };
+  }
+}
+
+async function claudenvHomeCheck() {
+  if (await pathExists(claudenvHome())) {
+    return { status: OK, msg: `~/.claudenv/ at ${claudenvHome()}` };
+  }
+  return {
+    status: WARN,
+    msg: `~/.claudenv/ not initialised — run \`claudenv memory init\``,
+  };
+}
+
+async function memoriesLayoutCheck() {
+  const required = [
+    memoriesDir(),
+    globalDecisionsDir(),
+    join(memoriesDir(), 'canon'),
+  ];
+  const missing = [];
+  for (const p of required) {
+    if (!(await pathExists(p))) missing.push(p);
+  }
+  if (missing.length === 0) {
+    return { status: OK, msg: 'memories/{decisions,canon}/ present' };
+  }
+  return {
+    status: WARN,
+    msg: `Missing: ${missing.map((p) => p.replace(claudenvHome(), '~/.claudenv')).join(', ')}`,
+  };
+}
+
+async function indexSizeCheck() {
+  if (!(await pathExists(indexMdPath()))) {
+    return { status: WARN, msg: 'INDEX.md absent — run `claudenv memory index`' };
+  }
+  const text = await readFile(indexMdPath(), 'utf-8');
+  const lines = text.split('\n').length;
+  if (lines <= 100) return { status: OK, msg: `INDEX.md ${lines} lines (cap 100)` };
+  return { status: WARN, msg: `INDEX.md ${lines} lines — consider rotation` };
+}
+
+async function vibeDecisionsCheck() {
+  const skill = join(homedir(), '.claude', 'skills', 'vibe-decisions', 'SKILL.md');
+  if (await pathExists(skill)) {
+    return { status: OK, msg: 'vibe-decisions skill installed globally' };
+  }
+  return {
+    status: WARN,
+    msg: 'vibe-decisions skill not installed — run `claudenv install --force`',
+  };
+}
+
+async function projectHooksCheck() {
+  const settingsPath = join(process.cwd(), '.claude', 'settings.json');
+  if (!(await pathExists(settingsPath))) {
+    return {
+      status: WARN,
+      msg: 'no .claude/settings.json in current project (run `/claudenv` in Claude Code)',
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    return { status: FAIL, msg: `.claude/settings.json is not valid JSON` };
+  }
+  const post = parsed?.hooks?.PostToolUse || [];
+  const hasLogger = post.some((b) =>
+    (b.hooks || []).some((h) => h.command && h.command.includes('decisions-logger'))
+  );
+  if (hasLogger) return { status: OK, msg: 'decisions-logger hook registered' };
+  return {
+    status: WARN,
+    msg: 'decisions-logger hook NOT registered in this project',
+  };
+}
+
+async function pythonModuleCheck() {
+  try {
+    execSync('python3 -c "import claudenv_memory"', { stdio: ['pipe', 'pipe', 'pipe'] });
+    return { status: OK, msg: 'claudenv-memory (Python) importable' };
+  } catch {
+    return {
+      status: WARN,
+      msg: 'claudenv-memory (Python) not installed — optional, `pip install claudenv-memory`',
+    };
+  }
+}
+
+async function countDecisionsCheck() {
+  let count = 0;
+  try {
+    const names = await readdir(globalDecisionsDir());
+    count = names.filter((n) => n.endsWith('.md')).length;
+  } catch {
+    /* no dir */
+  }
+  return { status: OK, msg: `${count} global decisions logged` };
+}
+
+export async function runDoctor() {
+  const checks = [
+    await nodeVersionCheck(),
+    await claudeCliCheck(),
+    await claudenvHomeCheck(),
+    await memoriesLayoutCheck(),
+    await indexSizeCheck(),
+    await vibeDecisionsCheck(),
+    await projectHooksCheck(),
+    await pythonModuleCheck(),
+    await countDecisionsCheck(),
+  ];
+
+  let hasFail = false;
+  const lines = [];
+  for (const c of checks) {
+    lines.push(`${c.status} ${c.msg}`);
+    if (c.status === FAIL) hasFail = true;
+  }
+
+  return { lines, hasFail };
+}

package/src/hooks/decisions-logger.js

@@ -0,0 +1,183 @@
+/**
+ * decisions-logger — PostToolUse hook handler for Write events.
+ *
+ * Validates files written to a memories/decisions/ directory (global or project).
+ * Path check FIRST — short-circuit non-decision writes without parsing content.
+ *
+ * Skill writes the file to the correct scope directly (see SKILL.md). This hook
+ * does NOT rewrite paths post-hoc — that creates ping-pong with future Claude
+ * turns. Hook only validates frontmatter, logs mismatches for `claudenv decisions
+ * fix --rescope`, and marks INDEX.md dirty for regeneration.
+ */
+
+import { readFile, writeFile, appendFile, mkdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+
+const DECISIONS_PATH_RE = /(?:^|\/)(?:memories|memories\/project)\/decisions\/[^/]+\.md$/;
+const VIBE_MARKER = '__VIBE_DECISION__';
+const REQUIRED_FIELDS = ['date', 'topic', 'chose', 'reason'];
+
+// CLAUDENV_HOME is resolved lazily so tests can override via process.env.CLAUDENV_HOME.
+function claudenvHome() {
+  return process.env.CLAUDENV_HOME || join(homedir(), '.claudenv');
+}
+
+/**
+ * Extract the fields we care about from a Claude Code PostToolUse event.
+ * Tolerant to schema variants — Claude Code has shipped a few.
+ *
+ * @param {object|null} event - Parsed JSON event from stdin (or null)
+ * @returns {{ filePath: string|null, content: string|null }}
+ */
+export function readDecisionsLoggerInput(event) {
+  if (!event || typeof event !== 'object') return { filePath: null, content: null };
+
+  const toolInput = event.tool_input || event.toolInput || event.input || {};
+  const filePath = toolInput.file_path ?? toolInput.filePath ?? toolInput.path ?? null;
+  const content = toolInput.content ?? toolInput.text ?? null;
+
+  return { filePath, content };
+}
+
+/**
+ * Decide whether this Write event concerns a decision file.
+ * Path match OR vibe marker in content. Path is the cheaper check, do it first.
+ */
+function isDecisionWrite({ filePath, content }) {
+  if (filePath && DECISIONS_PATH_RE.test(filePath)) return true;
+  if (content && content.includes(VIBE_MARKER)) return true;
+  return false;
+}
+
+/**
+ * Extract YAML frontmatter as a flat object. Minimal parser — handles
+ * `key: value` and `key: [a, b, c]` on a single line. Heavy structures fall
+ * through as raw strings; we only need to validate REQUIRED_FIELDS exist.
+ */
+function parseFrontmatter(content) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(content);
+  if (!match) return null;
+
+  const result = {};
+  for (const line of match[1].split('\n')) {
+    const m = /^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const key = m[1];
+    let value = m[2].trim();
+    if (value.startsWith('[') && value.endsWith(']')) {
+      value = value
+        .slice(1, -1)
+        .split(',')
+        .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+        .filter(Boolean);
+    } else {
+      value = value.replace(/^['"]|['"]$/g, '');
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Detect scope from path alone (project subdirectory marker).
+ * Recognises both the conventional `~/.claudenv/memories/decisions/` and any
+ * path that lives directly under the current CLAUDENV_HOME (for tests).
+ */
+function pathScope(filePath) {
+  if (!filePath) return null;
+  if (/\.claude\/memories\/decisions\//.test(filePath)) return 'project';
+  if (/\.claudenv\/memories\/decisions\//.test(filePath)) return 'global';
+  if (filePath.startsWith(join(claudenvHome(), 'memories', 'decisions'))) return 'global';
+  return null;
+}
+
+/**
+ * Append a line to ~/.claudenv/.log/decisions-logger.log.
+ * Best-effort — never throws.
+ */
+async function logWarning(message) {
+  try {
+    const home = claudenvHome();
+    await mkdir(join(home, '.log'), { recursive: true });
+    await appendFile(
+      join(home, '.log', 'decisions-logger.log'),
+      `${new Date().toISOString()} ${message}\n`,
+      'utf-8'
+    );
+  } catch {
+    /* swallow — logging must not break hook chain */
+  }
+}
+
+/**
+ * Touch the index-dirty flag so regen-index (SessionEnd) or post-iteration
+ * fallback knows to regenerate INDEX.md.
+ */
+async function markIndexDirty() {
+  try {
+    const home = claudenvHome();
+    await mkdir(home, { recursive: true });
+    await writeFile(join(home, '.index-dirty'), new Date().toISOString(), 'utf-8');
+  } catch {
+    /* swallow */
+  }
+}
+
+/**
+ * Main handler.
+ * @param {{filePath: string|null, content: string|null}} input
+ * @returns {Promise<{exitCode: number, message?: string}>}
+ */
+export async function handleDecisionsLogger(input) {
+  // 1. Hot-path short-circuit: not a decision write → done.
+  if (!isDecisionWrite(input)) {
+    return { exitCode: 0 };
+  }
+
+  // 2. We need the actual file content. Hooks fire AFTER Write succeeds, so
+  // reading the file from disk is authoritative even if `content` was truncated.
+  let fileText = input.content;
+  if (input.filePath) {
+    try {
+      fileText = await readFile(input.filePath, 'utf-8');
+    } catch {
+      // file unreadable — fall back to event content (may be null)
+    }
+  }
+
+  if (!fileText) {
+    await logWarning(`No content for ${input.filePath ?? '<unknown>'}`);
+    return { exitCode: 0 };
+  }
+
+  // 3. Validate frontmatter.
+  const fm = parseFrontmatter(fileText);
+  if (!fm) {
+    await logWarning(
+      `${input.filePath ?? '<unknown>'} matched decisions/ path but has no YAML frontmatter`
+    );
+    return { exitCode: 0 };
+  }
+
+  const missing = REQUIRED_FIELDS.filter((f) => !(f in fm));
+  if (missing.length) {
+    await logWarning(
+      `${basename(input.filePath ?? '?')} missing required fields: ${missing.join(', ')}`
+    );
+  }
+
+  // 4. Scope vs path consistency check (warn-only; do not rewrite).
+  const declared = fm.scope || 'global';
+  const fromPath = pathScope(input.filePath);
+  if (fromPath && fromPath !== declared) {
+    await logWarning(
+      `${basename(input.filePath ?? '?')} declares scope=${declared} but lives in ${fromPath} path — fix with: claudenv decisions fix --rescope`
+    );
+  }
+
+  // 5. Index is now stale.
+  await markIndexDirty();
+
+  return { exitCode: 0 };
+}

package/src/hooks/dispatcher.js

@@ -0,0 +1,91 @@
+/**
+ * Router for `claudenv hook <name>` — entry point for Claude Code hook scripts.
+ *
+ * Claude Code invokes registered hooks as shell commands with the hook event
+ * (JSON) piped on stdin. The dispatcher reads stdin, routes to a handler, and
+ * exits with 0 (allow) or 2 (block).
+ *
+ * Handlers MUST be fast (< 100ms for hot-path PostToolUse) and never throw
+ * uncaught — a thrown handler will surface to the user as a noisy hook failure.
+ */
+
+import { readDecisionsLoggerInput, handleDecisionsLogger } from './decisions-logger.js';
+import { handleRegenIndex } from './regen-index.js';
+
+/**
+ * Read stdin with a short idle timeout. Avoids hanging when the hook is invoked
+ * without piped input (manual `claudenv hook regen-index` from a non-TTY shell —
+ * background tasks, GH Actions, etc.).
+ *
+ * - TTY → return "" immediately (interactive call, no event expected)
+ * - Otherwise wait up to `idleMs` for the first byte; once data starts arriving
+ *   we drain to EOF normally.
+ */
+async function readStdin(idleMs = 200) {
+  if (process.stdin.isTTY) return '';
+
+  return await new Promise((resolve, reject) => {
+    let data = '';
+    let gotAnyData = false;
+    const timer = setTimeout(() => {
+      // No data appeared within idleMs and no EOF either — treat as no event.
+      if (!gotAnyData) {
+        process.stdin.removeAllListeners();
+        resolve('');
+      }
+    }, idleMs);
+
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => {
+      gotAnyData = true;
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+    process.stdin.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Dispatch a hook by name. Reads stdin, calls handler, prints any result, exits.
+ *
+ * @param {string} name - The hook name passed as `claudenv hook <name>`
+ */
+export async function dispatch(name) {
+  const stdin = await readStdin();
+  let event = null;
+  if (stdin.trim()) {
+    try {
+      event = JSON.parse(stdin);
+    } catch {
+      // Non-JSON input — pass raw string to handlers that want it.
+      event = { _raw: stdin };
+    }
+  }
+
+  switch (name) {
+    case 'decisions-logger': {
+      const input = readDecisionsLoggerInput(event);
+      const result = await handleDecisionsLogger(input);
+      if (result?.message) process.stdout.write(result.message + '\n');
+      process.exit(result?.exitCode ?? 0);
+      break;
+    }
+    case 'regen-index': {
+      const result = await handleRegenIndex({ event });
+      if (result?.message) process.stdout.write(result.message + '\n');
+      process.exit(result?.exitCode ?? 0);
+      break;
+    }
+    default: {
+      process.stderr.write(`Unknown hook: ${name}\n`);
+      process.stderr.write('Available: decisions-logger, regen-index\n');
+      process.exit(2);
+    }
+  }
+}

package/src/hooks/regen-index.js

@@ -0,0 +1,198 @@
+/**
+ * regen-index — SessionEnd hook handler and CLI command for INDEX.md generation.
+ *
+ * Scans ~/.claudenv/memories/decisions/ + <cwd>/.claude/memories/decisions/,
+ * picks the top-N most recent by `date:` frontmatter, and produces a compact
+ * INDEX.md briefing (~30-50 lines) that the next session reads via memory tool
+ * or via `--append-system-prompt` (loop).
+ *
+ * Idempotent. Hard-capped output size so it never bloats the cache.
+ */
+
+import { readFile, writeFile, readdir, mkdir, unlink, stat } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+
+const DEFAULT_RECENT_LIMIT = 5;
+const MAX_INDEX_LINES = 60;
+
+// Lazy resolution so tests can override via process.env.CLAUDENV_HOME.
+function claudenvHome() {
+  return process.env.CLAUDENV_HOME || join(homedir(), '.claudenv');
+}
+function memoriesDir() { return join(claudenvHome(), 'memories'); }
+function globalDecisionsDir() { return join(memoriesDir(), 'decisions'); }
+function userPrefsPath() { return join(memoriesDir(), 'user', 'preferences.md'); }
+function indexPath() { return join(memoriesDir(), 'INDEX.md'); }
+function dirtyFlagPath() { return join(claudenvHome(), '.index-dirty'); }
+
+/**
+ * Read YAML frontmatter into a flat object. Same minimal parser as decisions-logger.
+ */
+function parseFrontmatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) return null;
+  const result = {};
+  for (const line of match[1].split('\n')) {
+    const m = /^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let value = m[2].trim().replace(/^['"]|['"]$/g, '');
+    result[m[1]] = value;
+  }
+  return result;
+}
+
+/**
+ * Collect decision entries from one directory.
+ * @returns {Promise<Array<{file: string, date: string|null, topic: string, chose: string, scope: string}>>}
+ */
+async function collectDecisions(dir, scopeHint) {
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.md')) continue;
+    const full = join(dir, name);
+    let text;
+    try {
+      text = await readFile(full, 'utf-8');
+    } catch {
+      continue;
+    }
+    const fm = parseFrontmatter(text) || {};
+    out.push({
+      file: full,
+      name,
+      date: fm.date || null,
+      topic: fm.topic || name.replace(/\.md$/, ''),
+      chose: fm.chose || '',
+      scope: fm.scope || scopeHint,
+    });
+  }
+  return out;
+}
+
+/**
+ * Read user/preferences.md, return summary lines (up to N).
+ */
+async function summarizePrefs(maxLines = 8) {
+  try {
+    const text = await readFile(userPrefsPath(), 'utf-8');
+    return text
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l.startsWith('- '))
+      .slice(0, maxLines);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Generate INDEX.md content.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Project root to include project-scoped decisions from
+ * @param {number} [options.limit] - Max decisions to surface
+ */
+export async function regenIndex(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const limit = options.limit ?? DEFAULT_RECENT_LIMIT;
+
+  const global = await collectDecisions(globalDecisionsDir(), 'global');
+  const project = await collectDecisions(
+    join(cwd, '.claude', 'memories', 'decisions'),
+    'project'
+  );
+
+  const all = [...global, ...project];
+
+  // Sort newest first by date (ISO sorts lexicographically). Missing date = oldest.
+  all.sort((a, b) => {
+    if (!a.date && !b.date) return 0;
+    if (!a.date) return 1;
+    if (!b.date) return -1;
+    return b.date.localeCompare(a.date);
+  });
+
+  const recent = all.slice(0, limit);
+  const prefs = await summarizePrefs();
+
+  const lines = [];
+  lines.push('# claudenv memory — INDEX');
+  lines.push('');
+  lines.push(`> Auto-generated by \`claudenv hook regen-index\`. Last: ${new Date().toISOString()}`);
+  lines.push('');
+
+  lines.push('## Recent decisions');
+  lines.push('');
+  if (recent.length === 0) {
+    lines.push('_No decisions yet. Make a non-trivial technical choice; vibe-decisions will log it._');
+  } else {
+    for (const d of recent) {
+      const date = d.date ? d.date.slice(0, 10) : '?';
+      const scope = d.scope === 'project' ? '[project]' : '[global]';
+      const slug = basename(d.name, '.md');
+      lines.push(`- ${date} ${scope} **${d.topic}** → ${d.chose} (\`${slug}\`)`);
+    }
+  }
+  lines.push('');
+
+  if (prefs.length) {
+    lines.push('## Active preferences');
+    lines.push('');
+    for (const p of prefs) lines.push(p);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push(`Files: ${global.length} global, ${project.length} project decisions. Run \`claudenv decisions list\` for the full set.`);
+
+  // Hard cap to keep cache stable.
+  const capped = lines.slice(0, MAX_INDEX_LINES);
+
+  await mkdir(memoriesDir(), { recursive: true });
+  await writeFile(indexPath(), capped.join('\n') + '\n', 'utf-8');
+
+  // Clear dirty flag if present.
+  try {
+    await unlink(dirtyFlagPath());
+  } catch {
+    /* not present — fine */
+  }
+
+  return {
+    indexPath: indexPath(),
+    decisionCount: all.length,
+    recentCount: recent.length,
+  };
+}
+
+/**
+ * Read the dirty flag (returns true if INDEX.md needs regen).
+ */
+export async function isIndexDirty() {
+  try {
+    await stat(dirtyFlagPath());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Hook entry point — called by dispatcher on SessionEnd.
+ */
+export async function handleRegenIndex({ event } = {}) {
+  const cwd = event?.cwd || process.cwd();
+  const result = await regenIndex({ cwd });
+  return {
+    exitCode: 0,
+    message: `INDEX.md regenerated (${result.recentCount} recent of ${result.decisionCount} total decisions)`,
+  };
+}