@ijfw/memory-server 1.3.0

package/src/lib/atomic-io.js

@@ -0,0 +1,201 @@
+// Cross-platform atomic I/O helpers. Zero deps. POSIX + Windows NTFS.
+//
+// writeAtomic(path, data, opts) -- write to <path>.tmp.<rand>, fsync (POSIX),
+//   rename to final. Atomic on same volume on POSIX + NTFS (since Vista).
+//   Network FS / FAT32 -- logs warning, writes non-atomically; tolerable.
+//
+// readSafe(path, validator?) -- never throws. Returns {ok, data, error}.
+//   If validator(data) returns falsy/throws, returned as no-data path.
+//
+// withLock(lockPath, fn, opts) -- exclusive PID-file lock via O_EXCL.
+//   5s default wait with 50ms retry. On timeout returns {status:'locked', pid}.
+
+import { writeFileSync, openSync, closeSync, fsyncSync, renameSync, readFileSync,
+  existsSync, mkdirSync, unlinkSync, statSync, chmodSync } from 'node:fs';
+import { dirname, resolve as pathResolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { platform } from 'node:os';
+
+const IS_WIN = platform() === 'win32';
+
+export function writeAtomic(targetPath, data, opts = {}) {
+  const { mode = 0o600, ensureDir = true, fsyncDir = !IS_WIN } = opts;
+  const abs = pathResolve(targetPath);
+  const dir = dirname(abs);
+
+  if (ensureDir && !existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  // Refuse symlinks at target -- supply-chain hygiene per v3 sec 1
+  if (existsSync(abs)) {
+    try {
+      const st = statSync(abs);
+      if (st.isSymbolicLink && st.isSymbolicLink()) {
+        throw new Error(`refusing to overwrite symlink at ${abs}`);
+      }
+    } catch (e) {
+      if (e.message.startsWith('refusing')) throw e;
+    }
+  }
+
+  const tmp = `${abs}.tmp.${randomBytes(8).toString('hex')}`;
+  const buf = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+
+  let fd;
+  try {
+    fd = openSync(tmp, 'w', mode);
+    writeFileSync(fd, buf);
+    if (!IS_WIN) {
+      try { fsyncSync(fd); } catch { /* fsync may fail on some FS, tolerable */ }
+    }
+    closeSync(fd);
+    fd = null;
+
+    renameSync(tmp, abs);
+
+    if (fsyncDir) {
+      try {
+        const dfd = openSync(dir, 'r');
+        try { fsyncSync(dfd); } catch { /* dir fsync best-effort */ }
+        closeSync(dfd);
+      } catch { /* dir fsync optional */ }
+    }
+
+    try { chmodSync(abs, mode); } catch { /* perms best-effort, hot-path validates */ }
+  } catch (e) {
+    if (fd != null) try { closeSync(fd); } catch { /* */ }
+    try { if (existsSync(tmp)) unlinkSync(tmp); } catch { /* */ }
+    throw e;
+  }
+
+  return { ok: true, path: abs, bytes: Buffer.byteLength(buf) };
+}
+
+export function readSafe(targetPath, validator) {
+  try {
+    if (!existsSync(targetPath)) return { ok: false, error: 'enoent' };
+    const raw = readFileSync(targetPath, 'utf8');
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      return { ok: false, error: 'parse', message: e.message };
+    }
+    if (typeof validator === 'function') {
+      try {
+        const ok = validator(parsed);
+        if (!ok) return { ok: false, error: 'invalid', data: parsed };
+      } catch (e) {
+        return { ok: false, error: 'validator', message: e.message, data: parsed };
+      }
+    }
+    return { ok: true, data: parsed };
+  } catch (e) {
+    return { ok: false, error: 'io', message: e.message };
+  }
+}
+
+export function withLock(lockPath, fn, opts = {}) {
+  const { timeoutMs = 5000, retryMs = 50 } = opts;
+  const abs = pathResolve(lockPath);
+  const dir = dirname(abs);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const start = Date.now();
+  let acquired = false;
+  let heldByPid = null;
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const fd = openSync(abs, 'wx', 0o600);
+      try { writeFileSync(fd, String(process.pid)); } catch { /* */ }
+      closeSync(fd);
+      acquired = true;
+      break;
+    } catch (e) {
+      if (e.code === 'EEXIST') {
+        try {
+          const pidStr = readFileSync(abs, 'utf8').trim();
+          heldByPid = Number(pidStr) || null;
+          // Stale-lock detection -- if PID isn't running, reclaim
+          if (heldByPid && !pidAlive(heldByPid)) {
+            try { unlinkSync(abs); } catch { /* */ }
+            continue;
+          }
+        } catch { /* */ }
+        const waited = Date.now() - start;
+        const remaining = timeoutMs - waited;
+        if (remaining <= 0) break;
+        // Synchronous sleep via Atomics
+        sleepSync(Math.min(retryMs, remaining));
+      } else {
+        throw e;
+      }
+    }
+  }
+
+  if (!acquired) return { status: 'locked', pid: heldByPid };
+
+  try {
+    const result = fn();
+    return { status: 'ok', result };
+  } finally {
+    try { unlinkSync(abs); } catch { /* */ }
+  }
+}
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+function sleepSync(ms) {
+  const sab = new SharedArrayBuffer(4);
+  const view = new Int32Array(sab);
+  Atomics.wait(view, 0, 0, ms);
+}
+
+// Log rotation -- caller of writeAtomic for log files invokes this first.
+// Each log capped at 1MB; rotate to <name>.log.1, delete <name>.log.2.
+export function rotateLogIfNeeded(logPath, maxBytes = 1024 * 1024) {
+  try {
+    if (!existsSync(logPath)) return false;
+    const st = statSync(logPath);
+    if (st.size < maxBytes) return false;
+    const rot1 = `${logPath}.1`;
+    const rot2 = `${logPath}.2`;
+    try { if (existsSync(rot2)) unlinkSync(rot2); } catch { /* */ }
+    try { if (existsSync(rot1)) renameSync(rot1, rot2); } catch { /* */ }
+    try { renameSync(logPath, rot1); } catch { /* */ }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// URL redactor -- strip query strings before logging per v3 sec 15
+export function redactUrl(s) {
+  if (typeof s !== 'string') return s;
+  return s.replace(/(https?:\/\/[^\s?#]+)\?[^\s]*/g, '$1?<redacted>');
+}
+
+// ANSI-strip for safe console output of fetched content (CHANGELOG etc).
+// Strips ESC sequences + bell + non-printable controls except \n \t.
+export function stripAnsi(s) {
+  if (typeof s !== 'string') return '';
+  // ESC sequences (CSI + OSC + simple ESC + 8-bit CSI)
+  // eslint-disable-next-line no-control-regex
+  let out = s.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\][^\x07]*\x07/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b[@-Z\\-_]/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x9b[0-9;?]*[a-zA-Z]/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+  return out;
+}

package/src/lib/cache.js

@@ -0,0 +1,33 @@
+// Lightweight TTL cache with mtime-based invalidation. Zero deps.
+//
+// ttlCache(key, ttlMs, mtimeKeyFn, computeFn) -> value
+//   mtimeKeyFn is a FUNCTION called lazily -- only invoked when TTL has elapsed or cache is cold.
+//   Cache hits within TTL return immediately without invoking mtimeKeyFn or computeFn.
+//   mtimeKey: a string-quantizable invalidator (e.g. "<latest mtime>:<file count>").
+//   If mtimeKey changes after TTL expiry, cache is busted; if unchanged, cachedAt is refreshed.
+
+const store = new Map(); // key -> { value, cachedAt, mtimeKey }
+
+export function ttlCache(key, ttlMs, mtimeKeyFn, computeFn) {
+  if (process.env.IJFW_DASHBOARD_NO_CACHE === '1') return computeFn();
+  const now = Date.now();
+  const entry = store.get(key);
+  if (entry && (now - entry.cachedAt) < ttlMs) {
+    // Inside TTL -- fast path: no fs walk, no invalidator check.
+    return entry.value;
+  }
+  // TTL expired or cache miss -- now invoke the invalidator lazily.
+  const mtimeKey = mtimeKeyFn();
+  if (entry && entry.mtimeKey === mtimeKey) {
+    // Same data -- just refresh cachedAt, skip recompute.
+    entry.cachedAt = now;
+    return entry.value;
+  }
+  const value = computeFn();
+  store.set(key, { value, cachedAt: now, mtimeKey });
+  return value;
+}
+
+export function clearCache() {
+  store.clear();
+}

package/src/lib/npm-view.js

@@ -0,0 +1,104 @@
+// npm view helper -- regex-validated version string fetch with retry + log.
+// Used by both the SessionStart bg check and ijfw_update_check MCP tool.
+
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { rotateLogIfNeeded, redactUrl } from './atomic-io.js';
+
+const VERSION_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+const PKG = '@ijfw/install';
+
+export async function npmView(pkg = PKG, opts = {}) {
+  const { retries = 2, timeoutMs = 10_000, backoffMs = 2000 } = opts;
+  let lastErr = null;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const res = spawnSync('npm', ['view', pkg, 'version', '--json'], {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      // shell:true on Windows so npm.cmd resolves; harmless on POSIX.
+      shell: process.platform === 'win32',
+    });
+    if (res.error) {
+      lastErr = `spawn-${res.error.code || 'ERR'}: ${(res.error.message || String(res.error)).slice(0, 120)}`;
+      logFailure(pkg, lastErr);
+      if (attempt < retries && isTransient(res.error.code)) {
+        await sleep(backoffMs);
+        continue;
+      }
+      return { ok: false, error: 'spawn', message: lastErr };
+    }
+    if (res.signal) {
+      lastErr = `killed by ${res.signal} (likely network timeout)`;
+      logFailure(pkg, lastErr);
+      if (attempt < retries) {
+        await sleep(backoffMs);
+        continue;
+      }
+      return { ok: false, error: 'signal', message: lastErr };
+    }
+    if (res.status !== 0) {
+      lastErr = (res.stderr || '').trim() || `npm view exited ${res.status} with no stderr`;
+      logFailure(pkg, lastErr);
+      if (attempt < retries) {
+        await sleep(backoffMs);
+        continue;
+      }
+      return { ok: false, error: 'exit', message: lastErr };
+    }
+    const raw = (res.stdout || '').trim().replace(/^"|"$/g, '');
+    if (!VERSION_RE.test(raw)) {
+      logFailure(pkg, `malformed: ${raw.slice(0, 80)}`);
+      return { ok: false, error: 'malformed', message: raw.slice(0, 80) };
+    }
+    return { ok: true, version: raw };
+  }
+  return { ok: false, error: 'exhausted', message: lastErr };
+}
+
+function isTransient(code) {
+  return code === 'ENOTFOUND' || code === 'ETIMEDOUT' || code === 'ECONNRESET' || code === 'ECONNREFUSED';
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export function isVersionStringValid(s) {
+  return typeof s === 'string' && VERSION_RE.test(s);
+}
+
+export function compareSemver(a, b) {
+  // Returns -1 if a<b, 0 if eq, 1 if a>b. Pre-release sorts < release.
+  const parse = v => {
+    const [main, pre] = String(v).split('-', 2);
+    const nums = main.split('.').map(n => parseInt(n, 10) || 0);
+    while (nums.length < 3) nums.push(0);
+    return { nums, pre: pre || null };
+  };
+  const A = parse(a); const B = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if (A.nums[i] !== B.nums[i]) return A.nums[i] < B.nums[i] ? -1 : 1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (A.pre && !B.pre) return -1;
+  if (!A.pre && B.pre) return 1;
+  return A.pre < B.pre ? -1 : 1;
+}
+
+function logRoot() {
+  const r = process.env.IJFW_HOME || join(homedir(), '.ijfw');
+  const dir = join(r, 'logs');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+function logFailure(pkg, message) {
+  try {
+    const path = join(logRoot(), 'update-check.log');
+    rotateLogIfNeeded(path);
+    const line = `${new Date().toISOString()} ${pkg} ${redactUrl(String(message)).slice(0, 200)}\n`;
+    appendFileSync(path, line, { mode: 0o600 });
+  } catch { /* logging is best-effort */ }
+}

package/src/lib/status-card.js

@@ -0,0 +1,95 @@
+// Shared status-card composer -- one source of truth for the per-turn
+// "[ijfw] context: X% | 1.1.6 available" line that Codex Stop + Gemini
+// AfterAgent + (eventually) other-platform hooks all surface.
+//
+// Inputs:
+//   contextPct  number 0..100 (optional) -- estimated context-used percentage
+//                If null, the bar is omitted; only the update nudge surfaces.
+//   ijfwHome    string (optional) -- override for ~/.ijfw (testing)
+//
+// Output:
+//   string -- single-line card, or '' when nothing useful to surface.
+//   Caller is responsible for embedding into the platform-specific envelope
+//   (systemMessage / additionalContext / etc.).
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+function readJsonSafe(p) {
+  try { if (!existsSync(p)) return null; return JSON.parse(readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+function cmpSemver(a, b) {
+  const parse = v => {
+    const [main, pre] = String(v).split('-', 2);
+    const nums = main.split('.').map(n => parseInt(n, 10) || 0);
+    while (nums.length < 3) nums.push(0);
+    return { nums, pre: pre || null };
+  };
+  const A = parse(a); const B = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if (A.nums[i] !== B.nums[i]) return A.nums[i] < B.nums[i] ? -1 : 1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (A.pre && !B.pre) return -1;
+  if (!A.pre && B.pre) return 1;
+  return A.pre < B.pre ? -1 : 1;
+}
+
+export function composeStatusCard(opts = {}) {
+  const root = opts.ijfwHome || process.env.IJFW_HOME || join(homedir(), '.ijfw');
+  const state = readJsonSafe(join(root, 'state.json')) || {};
+  const cache = readJsonSafe(join(root, 'cache', 'update-check.json')) || {};
+  const settings = readJsonSafe(join(root, 'settings.json')) || {};
+
+  // Update segment with re-entrancy guard (matches statusline + prelude logic)
+  let updateSeg = '';
+  if (cache.last_latest_seen) {
+    const installed = state.installed_version || '0.0.0';
+    const lastApplied = state.last_applied_version;
+    const stillBehind = cmpSemver(installed, cache.last_latest_seen) < 0;
+    const reentrancyOk = !lastApplied || cmpSemver(lastApplied, cache.last_latest_seen) < 0;
+    if (stillBehind && reentrancyOk) {
+      updateSeg = `${cache.last_latest_seen} available`;
+    }
+  }
+
+  // Context segment (only when we have a number)
+  let ctxSeg = '';
+  const pct = opts.contextPct;
+  if (typeof pct === 'number' && isFinite(pct) && pct >= 0 && pct <= 100) {
+    const cb = settings.context_bar || {};
+    const style = cb.style || 'left';
+    const used = Math.round(pct);
+    const remaining = Math.max(0, 100 - used);
+    ctxSeg =
+      style === 'runway' ? `${remaining}% runway` :
+      style === 'classic' ? `${used}% used` :
+      `${remaining}% left`;
+  }
+
+  if (!updateSeg && !ctxSeg) return '';
+  const parts = [];
+  if (ctxSeg) parts.push(`context: ${ctxSeg}`);
+  if (updateSeg) parts.push(`update: ${updateSeg}`);
+  return `[ijfw] ${parts.join(' | ')}`;
+}
+
+// Estimate context % from a transcript file's byte size.
+// Heuristic shared with Codex's PreCompact workaround in session-end.sh.
+//   - Default model context window: 200_000 tokens (Claude Sonnet 4.6 ballpark).
+//   - Token estimate: bytes / 3.5 (rough English heuristic).
+//   - Returns null when transcript missing or empty.
+export function estimateContextPctFromTranscript(transcriptPath, opts = {}) {
+  const { modelContextTokens = 200_000, bytesPerToken = 3.5 } = opts;
+  try {
+    if (!transcriptPath || !existsSync(transcriptPath)) return null;
+    const sz = statSync(transcriptPath).size;
+    if (sz <= 0) return null;
+    const tokens = sz / bytesPerToken;
+    const pct = Math.min(99, Math.max(0, (tokens / modelContextTokens) * 100));
+    return pct;
+  } catch { return null; }
+}

package/src/lib/token.js

@@ -0,0 +1,85 @@
+// Crypto-random confirmation token issuance for MCP update flow.
+// Token is short (32 hex chars = 128 bits) and human-typeable.
+// Stored server-side at ~/.ijfw/run/<session>/update-token.json with expiry.
+
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { writeAtomic, readSafe } from './atomic-io.js';
+import { existsSync, mkdirSync, unlinkSync } from 'node:fs';
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 min
+
+export function generateToken() {
+  return randomBytes(16).toString('hex');
+}
+
+export function sessionDir(sessionId = 'default') {
+  // Sanitize -- per v3 sec 2: /^[a-zA-Z0-9_-]{8,64}$/, fallback to 'default'
+  const safe = /^[a-zA-Z0-9_-]{8,64}$/.test(sessionId) ? sessionId : 'default-session';
+  const root = process.env.IJFW_HOME || join(homedir(), '.ijfw');
+  const dir = join(root, 'run', safe);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+export function issueToken(sessionId, targetVersion, ttlMs = DEFAULT_TTL_MS) {
+  const token = generateToken();
+  const expiresAt = Date.now() + ttlMs;
+  const dir = sessionDir(sessionId);
+  const path = join(dir, 'update-token.json');
+  writeAtomic(path, {
+    schema_version: 1,
+    token,
+    target_version: targetVersion,
+    issued_at: Date.now(),
+    expires_at: expiresAt,
+    consumed: false,
+  });
+  return { token, expires_at: expiresAt, path };
+}
+
+export function validateToken(sessionId, candidateToken) {
+  const dir = sessionDir(sessionId);
+  const path = join(dir, 'update-token.json');
+  const r = readSafe(path, d => d && typeof d.token === 'string');
+  if (!r.ok) return { ok: false, error: 'no-token' };
+  const t = r.data;
+  if (t.consumed) return { ok: false, error: 'already-consumed' };
+  if (Date.now() > t.expires_at) return { ok: false, error: 'expired' };
+  if (t.token !== candidateToken) return { ok: false, error: 'mismatch' };
+  return { ok: true, target_version: t.target_version };
+}
+
+export function consumeToken(sessionId) {
+  const dir = sessionDir(sessionId);
+  const path = join(dir, 'update-token.json');
+  const r = readSafe(path);
+  if (!r.ok) return false;
+  writeAtomic(path, { ...r.data, consumed: true, consumed_at: Date.now() });
+  return true;
+}
+
+export function writePendingSentinel(sessionId, targetVersion, token) {
+  const dir = sessionDir(sessionId);
+  const path = join(dir, 'update-pending.json');
+  writeAtomic(path, {
+    schema_version: 1,
+    target_version: targetVersion,
+    token,
+    issued_at: Date.now(),
+  });
+  return path;
+}
+
+export function readPendingSentinel(sessionId) {
+  const dir = sessionDir(sessionId);
+  const path = join(dir, 'update-pending.json');
+  return readSafe(path, d => d && typeof d.token === 'string');
+}
+
+export function clearPendingSentinel(sessionId) {
+  const dir = sessionDir(sessionId);
+  const path = join(dir, 'update-pending.json');
+  try { if (existsSync(path)) unlinkSync(path); return true; } catch { return false; }
+}