hypomnema 1.1.0 → 1.2.0

package/hooks/hypo-web-fetch-ingest.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * hypo-web-fetch-ingest.mjs — PostToolUse hook (fix #2)
+ *
+ * When the LLM uses WebFetch or WebSearch, nudge it to follow §8.4 path A:
+ * "external research → /hypo:ingest into sources/". This hook produces a
+ * *signal*, not an automatic ingest call — per spec §5.4.6 Q-5.4.6:
+ *   "WebFetch/WebSearch 자동 ingest 시그널은 별도 hook(fix #2)으로 분리."
+ *
+ * Why signal-only (not direct ingest):
+ *   - slug derivation is LLM-driven (commands/ingest.md), so a hook cannot
+ *     reliably write to the canonical sources/<slug>.* path.
+ *   - duplicate-ingest detection is delegated to /hypo:ingest itself; the
+ *     nudge text says "이미 반영 여부 확인 후" so the LLM checks the page
+ *     graph before adding a new source.
+ *
+ * Output contract — Claude Code docs, "Add context for Claude":
+ *   PostToolUse uses **nested** hookSpecificOutput.additionalContext, NOT
+ *   the top-level additionalContext that UserPromptSubmit hooks use.
+ *   buildOutput() in hypo-shared.mjs is the top-level helper used by
+ *   hypo-first-prompt / hypo-lookup; intentionally not reused here. See
+ *   commit 515458f for the per-event matrix this codebase follows.
+ *
+ * URL redaction:
+ *   additionalContext lands in the transcript. Query strings and
+ *   fragments may carry tokens (?token=…, #access_token=…), so we emit
+ *   origin + pathname only. Malformed URLs are dropped to avoid raw
+ *   echoes.
+ *
+ * matcher choice:
+ *   hooks/hooks.json does not (today) propagate matcher/timeout through
+ *   scripts/init.mjs:mergeSettingsJson — the installer rewrites groups
+ *   as {hooks:[{type,command}]}. So we filter on tool_name internally
+ *   instead of declaring a matcher. Per-tool spawn cost (~39ms node
+ *   startup, measured 2026-05-23) is the trade-off; switch to a matcher
+ *   when the installer learns to preserve it.
+ *
+ * Fail-safe (spec §5.4.3 (e)): silent fail + {continue:true,
+ * suppressOutput:true}. PostToolUse fires only on successful tool calls;
+ * failures arrive on a separate PostToolUseFailure event, so no
+ * in-hook failure branch is needed.
+ */
+
+import { isGateSkipped } from './hypo-shared.mjs';
+
+let input = {};
+try {
+  const raw = await new Promise((r) => {
+    let d = '';
+    process.stdin.on('data', (c) => (d += c));
+    process.stdin.on('end', () => r(d));
+  });
+  input = raw ? JSON.parse(raw) : {};
+} catch (err) {
+  process.stderr.write(`[hypo-web-fetch-ingest] error: ${err?.message ?? String(err)}\n`);
+  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+  process.exit(0);
+}
+
+const context = buildContext(input);
+const output = { continue: true, suppressOutput: true };
+if (context) {
+  output.hookSpecificOutput = {
+    hookEventName: 'PostToolUse',
+    additionalContext: context,
+  };
+}
+console.log(JSON.stringify(output));
+
+function buildContext(data) {
+  if (isGateSkipped()) return null;
+  const tool = data?.tool_name ?? '';
+  if (tool === 'WebFetch') {
+    const url = redactUrl(data?.tool_input?.url);
+    if (!url) return null;
+    return (
+      `[WIKI AUTO-INGEST: WebFetch] ${url}\n` +
+      `Spec §8.4 path A: confirm this URL is not already represented in ` +
+      `sources/ or pages/, then call /hypo:ingest to capture it. ` +
+      `(URL redacted of query/hash for transcript safety.)`
+    );
+  }
+  if (tool === 'WebSearch') {
+    return (
+      `[WIKI AUTO-INGEST: WebSearch] external search performed.\n` +
+      `Spec §8.4 path A: any URL you fetch from these results should be ` +
+      `captured via /hypo:ingest — confirm it is not already in sources/ before ingesting.`
+    );
+  }
+  return null;
+}
+
+/**
+ * Reduce a URL to `origin + pathname` so query strings, fragments, and
+ * userinfo (`https://user:pass@host`) — which routinely carry
+ * credentials / session tokens — never reach the transcript via
+ * additionalContext. `new URL().origin` is protocol + host + port only,
+ * so userinfo is dropped for free.
+ *
+ * The protocol allow-list (http/https) is a defense-in-depth guard:
+ * non-web schemes like `file://`, `ftp://`, `data:` can produce
+ * surprising origins (e.g. `null/Users/...`) or pull a local path into
+ * the transcript, so they are rejected instead of redacted.
+ *
+ * Path-carried secrets (`https://host/path/<token>`) remain — keeping
+ * the path is the whole point of identifying *which* page to ingest, so
+ * full path redaction would defeat the nudge's purpose. The nudge text
+ * still tells the LLM to verify the URL before committing it.
+ *
+ * Returns null on malformed input or disallowed scheme.
+ */
+function redactUrl(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return null;
+  }
+}

package/hooks/version-check-fetch.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * version-check-fetch.mjs — detached update-check worker
+ *
+ * Spawned (detached, unref'd, stdio ignored) by the SessionStart hook ONLY when
+ * the cache is stale. It fetches the latest published versions for both
+ * channels and merges them into the cache, then exits. The hook never waits on
+ * it, so session start stays at 0ms added latency; the refreshed version is
+ * shown from the NEXT session.
+ *
+ * Best-effort throughout: any failure (offline, 404, timeout) leaves the cache
+ * untouched for that channel and exits 0 — never throws back at a hook.
+ *
+ * Usage: node version-check-fetch.mjs [cachePath]
+ */
+
+import { defaultCachePath, mergeLatest } from './version-check.mjs';
+
+const NPM_URL = 'https://registry.npmjs.org/hypomnema/latest';
+const PLUGIN_URL =
+  'https://raw.githubusercontent.com/sk-lim19f/Hypomnema/main/.claude-plugin/marketplace.json';
+const TIMEOUT_MS = 2000;
+
+async function fetchJson(url) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal, headers: { accept: 'application/json' } });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchNpmLatest() {
+  const data = await fetchJson(NPM_URL);
+  return data && typeof data.version === 'string' ? data.version : null;
+}
+
+async function fetchPluginLatest() {
+  const data = await fetchJson(PLUGIN_URL);
+  if (!data || !Array.isArray(data.plugins)) return null;
+  // Select by name rather than plugins[0]: a future marketplace.json could list
+  // more than one plugin or reorder entries, which would otherwise read the
+  // wrong version.
+  const entry = data.plugins.find((p) => p && p.name === 'hypomnema');
+  const v = entry && entry.version;
+  return typeof v === 'string' ? v : null;
+}
+
+async function main() {
+  const cachePath = process.argv[2] || defaultCachePath();
+  const [npmLatest, pluginLatest] = await Promise.all([fetchNpmLatest(), fetchPluginLatest()]);
+
+  const latest = {};
+  if (npmLatest) latest.npm = npmLatest;
+  if (pluginLatest) latest.plugin = pluginLatest;
+
+  // Even if both fetches fail we still stamp checkedAt so we don't hammer the
+  // network every single session while offline — the TTL backs off naturally.
+  try {
+    mergeLatest(cachePath, latest);
+  } catch {
+    /* best-effort */
+  }
+}
+
+main().then(
+  () => process.exit(0),
+  () => process.exit(0),
+);

package/hooks/version-check.mjs

@@ -0,0 +1,184 @@
+/**
+ * version-check.mjs — update-notifier core (pure logic + cache I/O)
+ *
+ * Hypomnema ships through TWO channels — the `hypomnema` npm package and a
+ * Claude Code plugin (marketplace `sk-lim19f/Hypomnema`). This module decides,
+ * given the cached "latest" versions and the installed version, whether to show
+ * an "update available" banner at session start.
+ *
+ * Design constraints (see ADR / teams review 2026-05-21):
+ *   - The SessionStart hook must never make a synchronous network call. It reads
+ *     ONLY the cache here; a detached worker (version-check-fetch.mjs) refreshes
+ *     the cache out-of-band. So everything in this file is offline + cheap.
+ *   - Per-channel state: npm and plugin `latest` can diverge (npm publish vs
+ *     marketplace commit happen at different times), so `latest` and
+ *     `notifiedFor` are keyed by channel — a single scalar would suppress or
+ *     repeat banners when the user switches channels.
+ *   - Cache writes are atomic (tmp + rename); the fetch worker MERGES rather
+ *     than overwrites so it never erases the hook's `notifiedFor` marks.
+ */
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+
+export const TTL_MS = 24 * 60 * 60 * 1000; // 24h
+export const CHANNELS = ['npm', 'plugin'];
+
+/**
+ * Cache lives under ~/.claude (Claude-hook-specific state), NOT inside the
+ * Obsidian vault ~/hypomnema — that directory is git-tracked, so a cache file
+ * there would create dirty status, sync noise, and accidental-commit / privacy
+ * risk (teams review (e), 2026-05-21).
+ */
+export function defaultCachePath(home = homedir()) {
+  return join(home, '.claude', 'hypomnema', 'cache', 'version-check.json');
+}
+
+// ── semver ───────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a semver string. Tolerates a leading `v` and ignores build metadata.
+ * Returns null for anything that isn't `MAJOR.MINOR.PATCH[-prerelease][+build]`.
+ */
+export function parseSemver(v) {
+  if (typeof v !== 'string') return null;
+  const m = v
+    .trim()
+    .replace(/^v/, '')
+    .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!m) return null;
+  return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] || '' };
+}
+
+/**
+ * Compare two semver strings. Returns -1 / 0 / 1, or null if either is invalid.
+ * A release outranks a prerelease of the same x.y.z (1.2.3 > 1.2.3-rc.1).
+ */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  for (const k of ['major', 'minor', 'patch']) {
+    if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (!pa.pre) return 1; // release > prerelease
+  if (!pb.pre) return -1;
+  return pa.pre < pb.pre ? -1 : 1; // lexicographic fallback (good enough)
+}
+
+// ── channel detection ──────────────────────────────────────────────────────
+
+/**
+ * Decide the active install channel from the package root path.
+ *
+ * The caller should pass the root derived from the RUNNING hook path
+ * (import.meta.url → ../..), with ~/.claude/hypo-pkg.json's pkgRoot only as a
+ * fallback: that metadata file has drifted before, and in a dual install
+ * (npm global + plugin) it names just one path. Reporting the inactive channel
+ * would hand the user the wrong update command (teams review (b), 2026-05-21).
+ *
+ * Plugin is checked before npm because a plugin install can itself live under a
+ * node_modules path, but never vice-versa.
+ */
+export function detectChannel(pkgRoot) {
+  if (typeof pkgRoot !== 'string' || !pkgRoot) return 'unknown';
+  const p = pkgRoot.replace(/\\/g, '/');
+  if (p.includes('/plugins/') || p.includes('/.claude/plugins/')) return 'plugin';
+  if (p.includes('/node_modules/')) return 'npm';
+  return 'unknown';
+}
+
+/** Channel-specific one-line update instruction. */
+export function buildUpdateLine(channel, current, latest) {
+  const head = `[Hypomnema] Update available! ${current} → ${latest}`;
+  if (channel === 'plugin') {
+    return `${head}\n  → run: /plugin marketplace update hypomnema  then  /reload-plugins`;
+  }
+  if (channel === 'npm') {
+    return `${head}\n  → run: npm install -g hypomnema`;
+  }
+  return `${head}\n  → npm i -g hypomnema  (or  /plugin marketplace update hypomnema && /reload-plugins)`;
+}
+
+// ── cache freshness + notice decision (pure) ─────────────────────────────────
+
+/**
+ * Is the cache fresh enough to skip a refresh? A `checkedAt` in the future
+ * (clock skew / corrupt cache) is treated as stale so the worker re-fetches.
+ */
+export function cacheIsFresh(cache, now = Date.now(), ttl = TTL_MS) {
+  if (!cache || typeof cache.checkedAt !== 'number') return false;
+  if (cache.checkedAt > now + 60_000) return false;
+  return now - cache.checkedAt < ttl;
+}
+
+/**
+ * Decide whether to show a banner. Returns { latest, line } or null.
+ * Skips when: unknown channel, no cached latest for the channel, invalid
+ * semver, current >= latest (incl. local dev where current > latest), or the
+ * channel was already notified for this exact latest version.
+ */
+export function computeNotice(cache, channel, current) {
+  if (!cache || channel === 'unknown' || !CHANNELS.includes(channel)) return null;
+  const latest = cache.latest && cache.latest[channel];
+  if (!latest) return null;
+  const cmp = compareSemver(current, latest);
+  if (cmp === null || cmp >= 0) return null;
+  const already = cache.notifiedFor && cache.notifiedFor[channel];
+  if (already === latest) return null;
+  return { latest, line: buildUpdateLine(channel, current, latest) };
+}
+
+// ── cache I/O (atomic) ───────────────────────────────────────────────────────
+
+/** Read + parse the cache; returns null on missing/corrupt file. */
+export function readCache(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Atomic write: tmp file in the same dir, then rename (last-writer-wins). */
+export function writeCacheAtomic(path, obj) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2));
+  renameSync(tmp, path);
+}
+
+/**
+ * Record that the banner for {channel: latest} has been shown, preserving the
+ * rest of the cache. Read-merge-write so concurrent worker refreshes and hook
+ * marks don't clobber each other's fields. Best-effort: swallows errors.
+ */
+export function markNotified(path, channel, latest) {
+  try {
+    const cache = readCache(path) || {};
+    cache.notifiedFor = { ...(cache.notifiedFor || {}), [channel]: latest };
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Merge freshly-fetched latest versions into the cache without erasing
+ * `notifiedFor`. Used by the detached fetch worker.
+ */
+export function mergeLatest(path, latest, now = Date.now()) {
+  const cache = readCache(path) || {};
+  cache.checkedAt = now;
+  cache.latest = { ...(cache.latest || {}), ...latest };
+  cache.notifiedFor = cache.notifiedFor || {};
+  writeCacheAtomic(path, cache);
+  return cache;
+}
+
+/** True if any opt-out env var is set. */
+export function isOptedOut(env = process.env) {
+  return Boolean(env.HYPO_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,14 @@
     ".claude-plugin/",
     "README.md"
   ],
-  "keywords": ["wiki", "llm", "claude", "claude-code", "personal-wiki", "knowledge-management"],
+  "keywords": [
+    "wiki",
+    "llm",
+    "claude",
+    "claude-code",
+    "personal-wiki",
+    "knowledge-management"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/sk-lim19f/Hypomnema.git"
@@ -32,6 +39,13 @@
   "scripts": {
     "test": "node tests/runner.mjs",
     "lint": "node scripts/lint.mjs",
-    "graph": "node scripts/graph.mjs"
+    "graph": "node scripts/graph.mjs",
+    "smoke-pack": "node scripts/smoke-pack.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm test && npm run lint && npm run smoke-pack"
+  },
+  "devDependencies": {
+    "prettier": "^3.8.3"
   }
 }