hypomnema 1.0.1 → 1.2.0

package/scripts/session-audit.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * session-audit.mjs — Hypomnema autonomy/observability audit
+ *
+ * Reads completed session transcripts and emits per-session metrics
+ * (search count, ingest count, URLs mentioned, feedback count) so the
+ * weekly observability report (Lane E) can compute autonomy scores.
+ *
+ * Transcript dual-source (ADR 0019):
+ *   1) Primary: <hypo-dir>/.cache/sessions/index.jsonl
+ *      Written by hooks/hypo-session-record.mjs (Stop hook).
+ *   2) Fallback: ~/.claude/projects/<encoded>/*.jsonl
+ *      Scanned directly when the index is missing/empty.
+ *
+ * The audit is heuristic. Classification rules:
+ *   - staleness-skip: transcript older than --max-age-days (default 30)
+ *   - search-0:      0 search/query tool uses
+ *   - search-many:   >= 5 search/query tool uses
+ *   - ingest-missed: >= 2 URLs in transcript and 0 ingest calls
+ *   - normal:        otherwise
+ *
+ * Usage:
+ *   node scripts/session-audit.mjs [--hypo-dir=<path>] [--limit N]
+ *                                  [--max-age-days N] [--json]
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+
+const HOME = homedir();
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, limit: 50, maxAgeDays: 30, json: false, fallbackAll: false };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--limit=')) args.limit = parseInt(arg.slice(8), 10) || 50;
+    else if (arg.startsWith('--max-age-days=')) args.maxAgeDays = parseInt(arg.slice(15), 10) || 30;
+    else if (arg === '--json') args.json = true;
+    else if (arg === '--fallback-all-projects') args.fallbackAll = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── transcript discovery ─────────────────────────────────────────────────────
+
+function readIndexEntries(hypoDir) {
+  const path = join(hypoDir, '.cache', 'sessions', 'index.jsonl');
+  if (!existsSync(path)) return [];
+  const entries = [];
+  for (const line of readFileSync(path, 'utf-8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const e = JSON.parse(trimmed);
+      if (e && e.transcript_path && e.session_id) entries.push(e);
+    } catch {
+      /* skip malformed lines */
+    }
+  }
+  // Deduplicate by session_id, keeping the latest entry.
+  const bySession = new Map();
+  for (const e of entries) bySession.set(e.session_id, e);
+  return [...bySession.values()];
+}
+
+// Claude Code encodes a working directory by replacing path separators with
+// hyphens, so `/Users/foo/wiki` becomes `-Users-foo-wiki`. We use this to
+// limit the fallback scan to the directory matching the wiki under audit
+// rather than every project on the machine.
+function encodeCwdForClaude(cwd) {
+  return String(cwd).replace(/\//g, '-');
+}
+
+function scanFallback(claudeProjectsDir, { scopeDir = null, all = false } = {}) {
+  if (!existsSync(claudeProjectsDir)) return [];
+  const subdirs = readdirSync(claudeProjectsDir).filter((d) =>
+    statSync(join(claudeProjectsDir, d)).isDirectory(),
+  );
+  let targets;
+  if (all) {
+    targets = subdirs;
+  } else if (scopeDir) {
+    const encoded = encodeCwdForClaude(scopeDir);
+    targets = subdirs.filter((d) => d === encoded);
+  } else {
+    targets = [];
+  }
+  const entries = [];
+  for (const dir of targets) {
+    const full = join(claudeProjectsDir, dir);
+    for (const file of readdirSync(full)) {
+      if (!file.endsWith('.jsonl')) continue;
+      const transcriptPath = join(full, file);
+      entries.push({
+        session_id: file.replace(/\.jsonl$/, ''),
+        transcript_path: transcriptPath,
+        recorded_at: statSync(transcriptPath).mtime.toISOString(),
+        source: 'fallback',
+      });
+    }
+  }
+  return entries;
+}
+
+export function loadSessionEntries(hypoDir, opts = {}) {
+  const primary = readIndexEntries(hypoDir);
+  if (primary.length > 0) return primary.map((e) => ({ ...e, source: e.source || 'index' }));
+  const fallbackDir = opts.fallbackDir ?? join(HOME, '.claude', 'projects');
+  // By default we restrict fallback to transcripts whose Claude-encoded path
+  // matches `scopeDir` (the wiki root). This keeps an empty wiki's report
+  // from harvesting unrelated `~/.claude/projects/*` sessions.
+  return scanFallback(fallbackDir, {
+    scopeDir: opts.scopeDir ?? hypoDir,
+    all: !!opts.fallbackAll,
+  });
+}
+
+// ── transcript parsing & metrics ─────────────────────────────────────────────
+
+const SEARCH_TOOLS = new Set(['Grep', 'WebSearch', 'WebFetch']);
+const SEARCH_CMDS = ['/hypo:query', '/query'];
+const INGEST_CMDS = ['/hypo:ingest', '/ingest'];
+const FEEDBACK_CMDS = ['/hypo:feedback', '/feedback'];
+
+function readTranscriptLines(transcriptPath) {
+  if (!existsSync(transcriptPath)) return [];
+  const out = [];
+  for (const line of readFileSync(transcriptPath, 'utf-8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      out.push(JSON.parse(trimmed));
+    } catch {
+      /* skip */
+    }
+  }
+  return out;
+}
+
+function extractText(entry) {
+  if (!entry) return '';
+  if (typeof entry.content === 'string') return entry.content;
+  if (Array.isArray(entry.content)) {
+    return entry.content.map((c) => (typeof c === 'string' ? c : c?.text || '')).join('\n');
+  }
+  if (entry.message?.content) return extractText({ content: entry.message.content });
+  return '';
+}
+
+function countUrls(text) {
+  const matches = text.match(/https?:\/\/\S+/g);
+  return matches ? matches.length : 0;
+}
+
+// Walk a transcript line for `tool_use` blocks at the top level AND nested
+// inside `message.content[]`. Real Claude Code transcripts put tool calls in
+// the nested form (`{ type:"assistant", message:{ content:[{type:"tool_use",
+// name:"Bash"}] } }`); legacy fixtures use the top-level form. Both must work.
+function extractToolNames(entry) {
+  const names = [];
+  if (!entry || typeof entry !== 'object') return names;
+  if (entry.type === 'tool_use') {
+    const n = entry.name || entry.tool_name;
+    if (n) names.push(n);
+  } else if (entry.tool_name || entry.name) {
+    names.push(entry.tool_name || entry.name);
+  }
+  const content = entry.message?.content ?? (Array.isArray(entry.content) ? entry.content : null);
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && typeof block === 'object' && block.type === 'tool_use') {
+        const n = block.name || block.tool_name;
+        if (n) names.push(n);
+      }
+    }
+  }
+  return names;
+}
+
+export function computeMetrics(transcriptLines) {
+  const metrics = { search_count: 0, ingest_count: 0, feedback_count: 0, urls: 0, messages: 0 };
+  for (const line of transcriptLines) {
+    metrics.messages++;
+    // Count tool_use blocks (top-level OR nested under message.content[]).
+    // Text scan is independent — tool_use blocks carry `input`, not `.text`,
+    // so extractText() won't double-count them.
+    for (const name of extractToolNames(line)) {
+      if (SEARCH_TOOLS.has(name)) metrics.search_count++;
+    }
+    const text = extractText(line);
+    if (!text) continue;
+    metrics.urls += countUrls(text);
+    for (const cmd of SEARCH_CMDS) if (text.includes(cmd)) metrics.search_count++;
+    for (const cmd of INGEST_CMDS) if (text.includes(cmd)) metrics.ingest_count++;
+    for (const cmd of FEEDBACK_CMDS) if (text.includes(cmd)) metrics.feedback_count++;
+  }
+  return metrics;
+}
+
+export function classify(metrics, ageDays, maxAgeDays) {
+  if (Number.isFinite(ageDays) && ageDays > maxAgeDays) return 'staleness-skip';
+  if (metrics.urls >= 2 && metrics.ingest_count === 0) return 'ingest-missed';
+  if (metrics.search_count >= 5) return 'search-many';
+  if (metrics.search_count === 0) return 'search-0';
+  return 'normal';
+}
+
+// ── main audit ───────────────────────────────────────────────────────────────
+
+export function auditEntries(entries, { maxAgeDays = 30, limit = 50, now = Date.now() } = {}) {
+  const sorted = [...entries].sort((a, b) =>
+    (b.recorded_at || '').localeCompare(a.recorded_at || ''),
+  );
+  const slice = sorted.slice(0, limit);
+  const results = [];
+  for (const entry of slice) {
+    const lines = readTranscriptLines(entry.transcript_path);
+    const metrics = computeMetrics(lines);
+    const recordedAt = entry.recorded_at ? Date.parse(entry.recorded_at) : NaN;
+    const ageDays = Number.isFinite(recordedAt) ? (now - recordedAt) / (24 * 60 * 60 * 1000) : NaN;
+    const classification = classify(metrics, ageDays, maxAgeDays);
+    results.push({
+      session_id: entry.session_id,
+      source: entry.source,
+      recorded_at: entry.recorded_at,
+      age_days: Number.isFinite(ageDays) ? +ageDays.toFixed(2) : null,
+      metrics,
+      classification,
+    });
+  }
+  return results;
+}
+
+function isMain() {
+  try {
+    return import.meta.url === `file://${process.argv[1]}`;
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  const args = parseArgs(process.argv);
+  const entries = loadSessionEntries(args.hypoDir, { fallbackAll: args.fallbackAll });
+  const results = auditEntries(entries, { maxAgeDays: args.maxAgeDays, limit: args.limit });
+
+  if (args.json) {
+    console.log(
+      JSON.stringify({ hypo_dir: args.hypoDir, count: results.length, results }, null, 2),
+    );
+    process.exit(0);
+  }
+
+  if (results.length === 0) {
+    console.log('No sessions found.');
+    console.log(`  Looked in: ${join(args.hypoDir, '.cache', 'sessions', 'index.jsonl')}`);
+    console.log(`  Fallback:  ~/.claude/projects/<encoded>/*.jsonl`);
+    process.exit(0);
+  }
+
+  const tally = {};
+  for (const r of results) tally[r.classification] = (tally[r.classification] || 0) + 1;
+
+  console.log(`Audited ${results.length} session(s) from ${results[0].source}:`);
+  for (const [k, v] of Object.entries(tally)) console.log(`  ${k.padEnd(14)} ${v}`);
+  console.log('');
+  console.log('Recent sessions:');
+  for (const r of results.slice(0, 10)) {
+    const m = r.metrics;
+    console.log(
+      `  [${r.classification.padEnd(14)}] ${r.session_id}  search=${m.search_count} ingest=${m.ingest_count} urls=${m.urls}`,
+    );
+  }
+}

package/scripts/smoke-pack.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * scripts/smoke-pack.mjs — pre-publish smoke test
+ *
+ * Runs `npm pack`, installs the resulting tarball into an isolated temp
+ * directory, and exercises the installed CLI to verify the published
+ * artifact actually works. Catches mistakes that local tests miss:
+ *   - `files:` / `.npmignore` excluding required assets
+ *   - `bin` entry pointing to a missing file
+ *   - runtime requires on paths not shipped in the tarball
+ *
+ * Usage:
+ *   node scripts/smoke-pack.mjs [--keep]
+ *
+ * --keep   Leave the temp directory in place for inspection on success.
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  readdirSync,
+  renameSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const REPO = join(fileURLToPath(new URL('.', import.meta.url)), '..');
+const KEEP = process.argv.includes('--keep');
+
+const PKG = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf-8'));
+const PKG_NAME = PKG.name;
+
+function run(cmd, args, opts = {}) {
+  const res = spawnSync(cmd, args, { stdio: 'pipe', encoding: 'utf-8', ...opts });
+  if (res.status !== 0) {
+    process.stderr.write(res.stdout || '');
+    process.stderr.write(res.stderr || '');
+    throw new Error(`${cmd} ${args.join(' ')} exited ${res.status}`);
+  }
+  return res;
+}
+
+function step(msg) {
+  console.log(`\n▸ ${msg}`);
+}
+
+const work = mkdtempSync(join(tmpdir(), 'hypo-smoke-'));
+const sandboxHome = join(work, 'home');
+const installRoot = join(work, 'install');
+const wikiDir = join(work, 'wiki');
+let cleanupOk = false;
+
+try {
+  step('npm pack');
+  const pack = run('npm', ['pack', '--json'], { cwd: REPO });
+  const meta = JSON.parse(pack.stdout)[0];
+  const tarball = join(REPO, meta.filename);
+  console.log(`  → ${meta.filename} (${meta.size} bytes, ${meta.entryCount} entries)`);
+
+  step(`install into ${installRoot}`);
+  run('mkdir', ['-p', installRoot]);
+  writeFileSync(
+    join(installRoot, 'package.json'),
+    JSON.stringify({
+      name: 'hypo-smoke-host',
+      version: '0.0.0',
+      private: true,
+    }) + '\n',
+  );
+  run('npm', ['install', '--no-audit', '--no-fund', '--silent', tarball], { cwd: installRoot });
+
+  // Move tarball into the work dir so it's not left in the repo.
+  renameSync(tarball, join(work, meta.filename));
+
+  const cliBin = join(installRoot, 'node_modules', '.bin', 'hypomnema');
+  if (!existsSync(cliBin)) {
+    throw new Error(`bin not installed at ${cliBin}`);
+  }
+
+  step('hypomnema --help (installed)');
+  const help = run(cliBin, ['--help']);
+  if (!help.stdout.includes('Usage: hypomnema')) {
+    throw new Error('--help output did not match expected banner');
+  }
+
+  step('hypomnema init --dry-run (installed)');
+  const dryEnv = { ...process.env, HOME: sandboxHome, HYPO_DIR: wikiDir };
+  const dry = run(
+    cliBin,
+    [
+      'init',
+      '--dry-run',
+      `--hypo-dir=${wikiDir}`,
+      '--no-hooks',
+      '--no-commands',
+      '--no-git-init',
+      '--no-shell',
+    ],
+    { env: dryEnv },
+  );
+  if (!/dry[\s-]?run/i.test(dry.stdout + dry.stderr)) {
+    console.log(dry.stdout);
+    throw new Error('init --dry-run did not announce dry-run mode');
+  }
+
+  step('verify shipped assets are present');
+  const required = [
+    'scripts/init.mjs',
+    'scripts/upgrade.mjs',
+    'hooks',
+    'commands',
+    'templates',
+    'README.md',
+  ];
+  const pkgRoot = join(installRoot, 'node_modules', PKG_NAME);
+  for (const rel of required) {
+    if (!existsSync(join(pkgRoot, rel))) {
+      throw new Error(`shipped tarball missing: ${rel}`);
+    }
+  }
+
+  step('hypomnema feedback-sync (installed) — check/write idempotency + bootstrap');
+  // Seed a fixture wiki + claude-home and exercise the feedback-sync surface
+  // through the installed CLI (proves the subcommand is routed + shipped and the
+  // Phase D bootstrap helper runs end-to-end). --check exits 1 on a fresh
+  // (un-written) projection, so use spawnSync (run() throws on non-zero).
+  const fbWiki = join(work, 'fb-wiki');
+  const fbHome = join(work, 'fb-home');
+  const fbProject = 'smoke';
+  run('mkdir', ['-p', join(fbWiki, 'pages', 'feedback')]);
+  run('mkdir', ['-p', join(fbHome, 'projects', fbProject, 'memory')]);
+  writeFileSync(
+    join(fbWiki, 'hypo-config.md'),
+    '---\ntitle: config\ntype: reference\n---\n# config\n',
+  );
+  writeFileSync(
+    join(fbWiki, 'pages', 'feedback', 'smoke-rule.md'),
+    [
+      '---',
+      'title: Smoke Rule',
+      'type: feedback',
+      'status: active',
+      'scope: global',
+      'tier: L1',
+      'targets: [project-memory, claude-learned]',
+      'sensitivity: public',
+      'priority: 4',
+      'memory_summary: smoke rule for the packed CLI',
+      'global_summary: always smoke-test the packed CLI',
+      'promote_to_global: true',
+      'reason: catch packaging regressions',
+      'source: session:2026-05-21',
+      'updated: 2026-05-21',
+      '---',
+      'body',
+      '',
+    ].join('\n'),
+  );
+  writeFileSync(
+    join(fbHome, 'CLAUDE.md'),
+    '# Global\n<learned_behaviors>\n- [2026-05-20] legacy hand rule — 이유: bootstrap source\n</learned_behaviors>\n',
+  );
+  writeFileSync(join(fbHome, 'projects', fbProject, 'memory', 'MEMORY.md'), '# Memory Index\n');
+
+  const fbArgs = [`--hypo-dir=${fbWiki}`, `--claude-home=${fbHome}`, `--project-id=${fbProject}`];
+  const fbRun = (extra) =>
+    spawnSync(cliBin, ['feedback-sync', ...extra, ...fbArgs], { encoding: 'utf-8' });
+
+  const fbCheck1 = fbRun(['--check']);
+  if (fbCheck1.status !== 1) {
+    throw new Error(
+      `feedback-sync --check on fresh projection expected exit 1, got ${fbCheck1.status}`,
+    );
+  }
+  const fbWrite = fbRun(['--write']);
+  if (fbWrite.status !== 0) {
+    throw new Error(
+      `feedback-sync --write expected exit 0, got ${fbWrite.status}: ${fbWrite.stderr}`,
+    );
+  }
+  if (
+    !readFileSync(join(fbHome, 'CLAUDE.md'), 'utf-8').includes(
+      'HYPO:FEEDBACK-SYNC:START source=smoke-rule',
+    )
+  ) {
+    throw new Error('feedback-sync --write did not project the managed block into CLAUDE.md');
+  }
+  const fbCheck2 = fbRun(['--check']);
+  if (fbCheck2.status !== 0) {
+    throw new Error(
+      `feedback-sync --check after --write expected clean exit 0, got ${fbCheck2.status}`,
+    );
+  }
+  const fbBootstrap = fbRun(['--bootstrap', '--dry-run']);
+  if (fbBootstrap.status !== 0 || !/would create draft/.test(fbBootstrap.stderr)) {
+    throw new Error(
+      `feedback-sync --bootstrap --dry-run did not announce drafts (exit ${fbBootstrap.status})`,
+    );
+  }
+
+  console.log('\n✓ smoke-pack passed');
+  cleanupOk = true;
+} catch (err) {
+  console.error(`\n✗ smoke-pack failed: ${err.message}`);
+  console.error(`  work dir preserved: ${work}`);
+  process.exitCode = 1;
+} finally {
+  if (cleanupOk && !KEEP) {
+    rmSync(work, { recursive: true, force: true });
+  } else if (KEEP) {
+    console.log(`\nwork dir kept: ${work}`);
+  }
+  // Sweep any stray tarballs left in the repo root from a crashed run.
+  for (const f of readdirSync(REPO)) {
+    if (f.startsWith(`${PKG_NAME}-`) && f.endsWith('.tgz')) {
+      rmSync(join(REPO, f), { force: true });
+    }
+  }
+}

package/scripts/stats.mjs

@@ -24,7 +24,7 @@ function parseArgs(argv) {
   const args = { hypoDir: null, json: false };
   for (const arg of argv.slice(2)) {
     if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
-    else if (arg === '--json')         args.json = true;
+    else if (arg === '--json') args.json = true;
   }
   if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
   return args;
@@ -52,14 +52,17 @@ function parseFrontmatter(content) {
   for (const line of m[1].split('\n')) {
     const idx = line.indexOf(':');
     if (idx < 0) continue;
-    fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    fm[line.slice(0, idx).trim()] = line
+      .slice(idx + 1)
+      .trim()
+      .replace(/^["']|["']$/g, '');
   }
   return fm;
 }
 
 function listDirs(dir) {
   if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter(e => {
+  return readdirSync(dir).filter((e) => {
     if (e.startsWith('.')) return false;
     return statSync(join(dir, e)).isDirectory();
   });
@@ -69,7 +72,7 @@ function getLastActivity(hypoDir) {
   const logPath = join(hypoDir, 'log.md');
   if (!existsSync(logPath)) return null;
   const content = readFileSync(logPath, 'utf-8');
-  const dates = [...content.matchAll(/\b(\d{4}-\d{2}-\d{2})\b/g)].map(m => m[1]);
+  const dates = [...content.matchAll(/\b(\d{4}-\d{2}-\d{2})\b/g)].map((m) => m[1]);
   return dates.length ? dates[dates.length - 1] : null;
 }
 
@@ -79,9 +82,13 @@ const args = parseArgs(process.argv);
 
 const ignorePatterns = loadHypoIgnore(args.hypoDir);
 const pageFiles = collectMdFiles(join(args.hypoDir, 'pages'), [], args.hypoDir, ignorePatterns);
-const projects  = listDirs(join(args.hypoDir, 'projects'));
-const sources   = existsSync(join(args.hypoDir, 'sources'))
-  ? readdirSync(join(args.hypoDir, 'sources')).filter(e => !e.startsWith('.') && !isIgnored(join(args.hypoDir, 'sources', e), args.hypoDir, ignorePatterns))
+const projects = listDirs(join(args.hypoDir, 'projects'));
+const sources = existsSync(join(args.hypoDir, 'sources'))
+  ? readdirSync(join(args.hypoDir, 'sources')).filter(
+      (e) =>
+        !e.startsWith('.') &&
+        !isIgnored(join(args.hypoDir, 'sources', e), args.hypoDir, ignorePatterns),
+    )
   : [];
 
 const typeCounts = {};
@@ -89,9 +96,16 @@ let missingFrontmatter = 0;
 
 for (const f of pageFiles) {
   let content;
-  try { content = readFileSync(f, 'utf-8'); } catch { continue; }
+  try {
+    content = readFileSync(f, 'utf-8');
+  } catch {
+    continue;
+  }
   const fm = parseFrontmatter(content);
-  if (!fm) { missingFrontmatter++; continue; }
+  if (!fm) {
+    missingFrontmatter++;
+    continue;
+  }
   const t = fm.type || 'unknown';
   typeCounts[t] = (typeCounts[t] || 0) + 1;
 }
@@ -100,7 +114,7 @@ let adrCount = 0;
 for (const p of projects) {
   const decisionsDir = join(args.hypoDir, 'projects', p, 'decisions');
   if (existsSync(decisionsDir)) {
-    adrCount += readdirSync(decisionsDir).filter(f => f.endsWith('.md')).length;
+    adrCount += readdirSync(decisionsDir).filter((f) => f.endsWith('.md')).length;
   }
 }