hypomnema 1.0.0

package/scripts/lint.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * Hypomnema lint script
+ *
+ * Validates wiki pages for frontmatter correctness and broken wikilinks.
+ *
+ * Usage:
+ *   node scripts/lint.mjs [options]
+ *
+ * Options:
+ *   --hypo-dir=<path>   Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --json              Output results as JSON
+ *   --fix               Auto-add missing `updated` field (safe repairs only)
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, extname, basename } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { SESSION_STATE_NEXT_HEADINGS } from '../hooks/hypo-shared.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+
+// ── arg parsing ──────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, json: false, fix: 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 === '--fix')          args.fix  = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── frontmatter parser ────────────────────────────────────────────────────────
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const fm = {};
+  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, '');
+  }
+  return fm;
+}
+
+// ── page collector ────────────────────────────────────────────────────────────
+
+function collectPages(dir, root, pages = [], ignorePatterns = []) {
+  if (!existsSync(dir)) return pages;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (isIgnored(full, root, ignorePatterns)) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      collectPages(full, root, pages, ignorePatterns);
+    } else if (extname(entry) === '.md' && !entry.startsWith('.')) {
+      pages.push({ path: full, rel: relative(root, full) });
+    }
+  }
+  return pages;
+}
+
+// ── slug map ─────────────────────────────────────────────────────────────────
+
+function buildSlugMap(pages) {
+  const map = new Set();
+  for (const { rel } of pages) {
+    map.add(rel.replace(/\.md$/, '').replace(/\\/g, '/'));
+    map.add(basename(rel, '.md'));
+  }
+  return map;
+}
+
+// ── wikilink extractor ────────────────────────────────────────────────────────
+
+function extractWikilinks(content) {
+  const links = [];
+  for (const m of content.matchAll(/\[\[([^\]|#]+?)(?:[|#][^\]]*?)?\]\]/g)) {
+    links.push(m[1].trim());
+  }
+  return links;
+}
+
+// ── lint checks ───────────────────────────────────────────────────────────────
+
+const REQUIRED_FIELDS = ['title', 'type'];
+const VALID_TYPES = [
+  'concept', 'source-summary', 'entity', 'tool-eval', 'prompt-pattern',
+  'playbook', 'learning', 'tip', 'feedback', 'reference', 'synthesis',
+  'weekly-journal', 'prd', 'adr', 'session-log', 'session-state',
+  'project-index', 'postmortem', 'open-questions', 'schema', 'source',
+];
+
+const issues = [];
+
+function issue(severity, rel, msg, fullPath = null) {
+  issues.push({ severity, file: rel, message: msg, path: fullPath });
+}
+
+function hasHeading(content, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^##\\s+${escaped}\\s*$`, 'm').test(content);
+}
+
+function lintSessionStateHeadings(content, rel) {
+  if (!rel.match(/^projects\/[^/]+\/session-state\.md$/)) return;
+
+  if (!SESSION_STATE_NEXT_HEADINGS.some(heading => hasHeading(content, heading))) {
+    issue(
+      'error',
+      rel,
+      `Missing required session-state heading: one of ${SESSION_STATE_NEXT_HEADINGS.map(h => `## ${h}`).join(', ')}`
+    );
+  }
+}
+
+function lintPage({ path, rel }, slugMap) {
+  let content;
+  try { content = readFileSync(path, 'utf-8'); } catch { return; }
+
+  if (!content.match(/^---\r?\n/)) {
+    issue('warn', rel, 'No frontmatter found');
+    return;
+  }
+
+  const fm = parseFrontmatter(content);
+  if (!fm) {
+    issue('error', rel, 'Malformed frontmatter (unclosed ---)');
+    return;
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!fm[field]) issue('error', rel, `Missing required frontmatter field: ${field}`);
+  }
+
+  if (fm.type && !VALID_TYPES.includes(fm.type)) {
+    issue('warn', rel, `Unknown type: "${fm.type}"`);
+  }
+
+  if (!fm.updated) {
+    issue('warn', rel, 'Missing frontmatter field: updated', path);
+  }
+
+  lintSessionStateHeadings(content, rel);
+
+  for (const link of extractWikilinks(content)) {
+    if (!slugMap.has(link)) {
+      issue('warn', rel, `Broken wikilink: [[${link}]]`);
+    }
+  }
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv);
+
+const ignorePatterns = loadHypoIgnore(args.hypoDir);
+const scanDirs = ['pages', 'projects'].map(d => join(args.hypoDir, d));
+const pages = scanDirs.flatMap(d => collectPages(d, args.hypoDir, [], ignorePatterns));
+const slugMap = buildSlugMap(pages);
+
+for (const page of pages) lintPage(page, slugMap);
+
+if (args.fix) {
+  const today = new Date().toISOString().slice(0, 10);
+  const fixed = new Set();
+  for (const iss of issues) {
+    if (iss.severity === 'warn' && iss.message === 'Missing frontmatter field: updated' && iss.path) {
+      const content = readFileSync(iss.path, 'utf-8');
+      const fmMatch = /^---\r?\n[\s\S]*?\r?\n---/.exec(content);
+      if (fmMatch) {
+        const lineEnding = fmMatch[0].includes('\r\n') ? '\r\n' : '\n';
+        const closingTag = `${lineEnding}---`;
+        const insertAt = fmMatch.index + fmMatch[0].lastIndexOf(closingTag);
+        if (insertAt < 0) continue;
+        const fixedContent = content.slice(0, insertAt) + `${lineEnding}updated: ${today}` + content.slice(insertAt);
+        writeFileSync(iss.path, fixedContent);
+        fixed.add(iss.path);
+      }
+    }
+  }
+  if (fixed.size > 0) {
+    issues.splice(0, issues.length, ...issues.filter(
+      i => !(i.severity === 'warn' && i.message === 'Missing frontmatter field: updated' && fixed.has(i.path))
+    ));
+  }
+}
+
+const errors = issues.filter(i => i.severity === 'error');
+const warns  = issues.filter(i => i.severity === 'warn');
+
+if (args.json) {
+  const toOut = ({ severity, file, message }) => ({ severity, file, message });
+  console.log(JSON.stringify({ ok: errors.length === 0, errors: errors.map(toOut), warns: warns.map(toOut), total: issues.length }, null, 2));
+} else {
+  if (issues.length === 0) {
+    console.log('✓ No lint issues found');
+  } else {
+    for (const { severity, file, message } of issues) {
+      const icon = severity === 'error' ? '✗' : '⚠';
+      console.log(`${icon} ${file}: ${message}`);
+    }
+    console.log(`\n${errors.length} error(s), ${warns.length} warning(s)`);
+  }
+}
+
+process.exit(errors.length > 0 ? 1 : 0);

package/scripts/query.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * Hypomnema query script
+ *
+ * Full-text search across wiki pages and projects.
+ * Returns matching files with a context excerpt and frontmatter summary.
+ * Used by /hypo:query to surface relevant pages before Claude synthesizes.
+ *
+ * Usage:
+ *   node scripts/query.mjs --q="<search terms>" [options]
+ *
+ * Options:
+ *   --hypo-dir=<path>   Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --q=<query>         Search query (required)
+ *   --limit=<n>         Max results (default: 10)
+ *   --json              Output as JSON
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, extname } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+
+// ── arg parsing ──────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, query: null, limit: 10, json: false };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--q='))     args.query  = arg.slice(4);
+    else if (arg.startsWith('--limit=')) args.limit  = parseInt(arg.slice(8), 10) || 10;
+    else if (arg === '--json')           args.json   = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function collectMdFiles(dir, root, acc = [], ignorePatterns = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (isIgnored(full, root, ignorePatterns)) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) collectMdFiles(full, root, acc, ignorePatterns);
+    else if (extname(entry) === '.md') acc.push({ path: full, rel: relative(root, full) });
+  }
+  return acc;
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const fm = {};
+  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, '');
+  }
+  return fm;
+}
+
+function escapeRegex(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function scoreAndExcerpt(content, terms) {
+  const lower = content.toLowerCase();
+  let score = 0;
+  for (const t of terms) score += (lower.match(new RegExp(escapeRegex(t), 'g')) || []).length;
+
+  // find first matching line for excerpt
+  const lines = content.split('\n');
+  let excerpt = '';
+  for (const line of lines) {
+    if (terms.some(t => line.toLowerCase().includes(t))) {
+      excerpt = line.trim().slice(0, 120);
+      break;
+    }
+  }
+  return { score, excerpt };
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv);
+
+if (!args.query) {
+  console.error('Error: --q=<query> is required');
+  process.exit(1);
+}
+
+const terms = args.query.toLowerCase().split(/\s+/).filter(Boolean);
+const ignorePatterns = loadHypoIgnore(args.hypoDir);
+const scanDirs = ['pages', 'projects'].map(d => join(args.hypoDir, d));
+const files = scanDirs.flatMap(d => collectMdFiles(d, args.hypoDir, [], ignorePatterns));
+
+const results = [];
+
+for (const { path, rel } of files) {
+  let content;
+  try { content = readFileSync(path, 'utf-8'); } catch { continue; }
+  const { score, excerpt } = scoreAndExcerpt(content, terms);
+  if (score === 0) continue;
+  const fm = parseFrontmatter(content);
+  results.push({ slug: rel.replace(/\.md$/, ''), title: fm.title || rel, type: fm.type || '', score, excerpt });
+}
+
+results.sort((a, b) => b.score - a.score);
+const top = results.slice(0, args.limit);
+
+if (args.json) {
+  console.log(JSON.stringify(top, null, 2));
+} else {
+  if (top.length === 0) {
+    console.log(`No results for: ${args.query}`);
+  } else {
+    console.log(`Found ${results.length} result(s) for "${args.query}" (showing ${top.length}):\n`);
+    for (const r of top) {
+      console.log(`[[${r.slug}]] — ${r.title}${r.type ? ` (${r.type})` : ''} [score: ${r.score}]`);
+      if (r.excerpt) console.log(`  ${r.excerpt}`);
+    }
+  }
+}

package/scripts/resume.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Hypomnema resume script
+ *
+ * Reads the session-state.md for a project and outputs the next-tasks section.
+ * Used by /hypo:resume to surface what was left off before Claude continues.
+ *
+ * Usage:
+ *   node scripts/resume.mjs [options]
+ *
+ * Options:
+ *   --hypo-dir=<path>     Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --project=<name>      Project name (default: most recently active from hot.md)
+ *   --json                Output as JSON
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+
+// ── arg parsing ──────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, project: null, json: false };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir='))  args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--project=')) args.project = arg.slice(10);
+    else if (arg === '--json')           args.json    = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── active project from hot.md ───────────────────────────────────────────────
+
+function resolveActiveProject(hypoDir) {
+  const hotPath = join(hypoDir, 'hot.md');
+  if (!existsSync(hotPath)) return null;
+
+  const content = readFileSync(hotPath, 'utf-8');
+  // Canonical hot.md uses wikilinks: | name | date | [[projects/slug/hot]] |
+  // Pick the most recent row by the date column when present.
+  const wikiRows = [...content.matchAll(/\|\s*([^|]+?)\s*\|\s*(\d{4}-\d{2}-\d{2})?\s*\|\s*\[\[projects\/([^\]/]+)\/[^\]]+\]\]/g)]
+    .map(m => ({ name: m[1].trim(), date: m[2] || '', slug: m[3] }));
+  if (wikiRows.length > 0) {
+    wikiRows.sort((a, b) => b.date.localeCompare(a.date));
+    return wikiRows[0].slug;
+  }
+  // Legacy markdown-link rows: | [name](projects/name/...) | ...
+  const mdRow = content.match(/\|\s*\[([^\]]+)\]\(projects\/([^/)]+)/);
+  if (mdRow) return mdRow[2];
+
+  // fallback: most recently modified project with a session-state.md
+  const projectsDir = join(hypoDir, 'projects');
+  if (!existsSync(projectsDir)) return null;
+
+  let latest = null;
+  let latestMtime = 0;
+  for (const p of readdirSync(projectsDir)) {
+    const ssPath = join(projectsDir, p, 'session-state.md');
+    if (!existsSync(ssPath)) continue;
+    const mtime = statSync(ssPath).mtimeMs;
+    if (mtime > latestMtime) { latestMtime = mtime; latest = p; }
+  }
+  return latest;
+}
+
+// ── read session state ────────────────────────────────────────────────────────
+
+function readSessionState(hypoDir, project) {
+  const ssPath = join(hypoDir, 'projects', project, 'session-state.md');
+  if (!existsSync(ssPath)) return null;
+  return readFileSync(ssPath, 'utf-8');
+}
+
+function readHot(hypoDir, project) {
+  const hotPath = join(hypoDir, 'projects', project, 'hot.md');
+  if (!existsSync(hotPath)) return null;
+  return readFileSync(hotPath, 'utf-8');
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv);
+
+const project = args.project || resolveActiveProject(args.hypoDir);
+
+if (!project) {
+  console.error('Error: no active project found. Use --project=<name> or create a hot.md entry.');
+  process.exit(1);
+}
+
+const sessionState = readSessionState(args.hypoDir, project);
+if (!sessionState) {
+  console.error(`Error: no session-state.md found for project "${project}"`);
+  process.exit(1);
+}
+
+const hotContent = readHot(args.hypoDir, project);
+
+if (args.json) {
+  console.log(JSON.stringify({ project, sessionState, hot: hotContent }, null, 2));
+  process.exit(0);
+}
+
+console.log(`Project: ${project}`);
+console.log(`State: projects/${project}/session-state.md\n`);
+console.log('─'.repeat(60));
+console.log(sessionState.trim());
+
+if (hotContent) {
+  console.log('\n' + '─'.repeat(60));
+  console.log('Background (hot.md):');
+  console.log(hotContent.trim());
+}

package/scripts/stats.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Hypomnema stats script
+ *
+ * Reports statistics about the wiki: page counts by type, project count,
+ * source count, ADR count, and last activity date.
+ *
+ * Usage:
+ *   node scripts/stats.mjs [options]
+ *
+ * Options:
+ *   --hypo-dir=<path>   Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --json              Output as JSON
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+
+// ── arg parsing ──────────────────────────────────────────────────────────────
+
+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;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (hypoDir && isIgnored(full, hypoDir, ignorePatterns)) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) collectMdFiles(full, acc, hypoDir, ignorePatterns);
+    else if (extname(entry) === '.md') acc.push(full);
+  }
+  return acc;
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const fm = {};
+  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, '');
+  }
+  return fm;
+}
+
+function listDirs(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(e => {
+    if (e.startsWith('.')) return false;
+    return statSync(join(dir, e)).isDirectory();
+  });
+}
+
+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]);
+  return dates.length ? dates[dates.length - 1] : null;
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+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 typeCounts = {};
+let missingFrontmatter = 0;
+
+for (const f of pageFiles) {
+  let content;
+  try { content = readFileSync(f, 'utf-8'); } catch { continue; }
+  const fm = parseFrontmatter(content);
+  if (!fm) { missingFrontmatter++; continue; }
+  const t = fm.type || 'unknown';
+  typeCounts[t] = (typeCounts[t] || 0) + 1;
+}
+
+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;
+  }
+}
+
+const lastActivity = getLastActivity(args.hypoDir);
+
+const stats = {
+  pages: { total: pageFiles.length, byType: typeCounts, missingFrontmatter },
+  projects: projects.length,
+  sources: sources.length,
+  adrs: adrCount,
+  lastActivity,
+};
+
+if (args.json) {
+  console.log(JSON.stringify(stats, null, 2));
+} else {
+  console.log(`Pages:    ${pageFiles.length} total`);
+  const typeEntries = Object.entries(typeCounts).sort((a, b) => b[1] - a[1]);
+  if (typeEntries.length) {
+    console.log(`  by type: ${typeEntries.map(([t, n]) => `${t} (${n})`).join(', ')}`);
+  }
+  if (missingFrontmatter) {
+    console.log(`  missing frontmatter: ${missingFrontmatter}`);
+  }
+  console.log(`Projects: ${projects.length}`);
+  console.log(`Sources:  ${sources.length}`);
+  console.log(`ADRs:     ${adrCount}`);
+  if (lastActivity) console.log(`Last activity: ${lastActivity}`);
+}