@ijfw/memory-server 1.3.0

package/src/prompt-check.js

@@ -0,0 +1,171 @@
+/**
+ * IJFW prompt-check -- deterministic vague-prompt detector.
+ *
+ * Pure functions, no I/O. Safe to call from MCP tool handler or import into
+ * a hook script. Returns { vague, signals, suggestion, bypass_reason? }.
+ *
+ * Design constraints (per AUDIT.md):
+ *   - No LLM calls, no network. Pure regex.
+ *   - Fire only when >=2 signals trip AND prompt is short AND has no target.
+ *   - Single-signal trips are silent (low FP rate).
+ *   - Override: leading `*` or substring "ijfw off" bypasses entirely.
+ *   - Positive framing in any user-visible suggestion.
+ */
+
+// 7-rule vagueness taxonomy from research (rule 3).
+const RULES = [
+  {
+    id: 'bare_verb',
+    // Bare imperative + no object. Token count <6 reduces FP on real questions.
+    test: (text) => {
+      const t = text.trim().toLowerCase();
+      const tokens = t.split(/\s+/);
+      if (tokens.length >= 6) return false;
+      return /^(fix|refactor|improve|clean\s*up|optimi[sz]e|update|review|check|test|debug|analy[sz]e|handle|sort\s*out|tidy)\b/.test(t);
+    }
+  },
+  {
+    id: 'unresolved_anaphora',
+    // "this/that/it" sentence-start. Hook can't see prior turns reliably,
+    // so this is heuristic -- combined with no_target it's a strong signal.
+    test: (text) => /^(this|that|it|these|those|the\s+(bug|issue|file|code|function|error|problem))\b/i.test(text.trim())
+  },
+  {
+    id: 'abstract_goal',
+    // "make it better" / "production-ready" / etc. without acceptance criteria.
+    test: (text) => {
+      const hasAbstract = /\b(better|cleaner|nicer|more\s+robust|production[\s-]?ready|proper|correct|good|nice|right)\b/i.test(text);
+      if (!hasAbstract) return false;
+      // Mitigates: contains a metric or test/path reference.
+      const hasMetric = /\d+\s*(ms|%|x|kb|mb|sec|s\b|tests?\b|users?\b)/i.test(text);
+      const hasPath = /[\w./-]+\.\w{1,5}(\b|:)|src\/|tests?\//i.test(text);
+      return !hasMetric && !hasPath;
+    }
+  },
+  {
+    id: 'no_target',
+    // No file path, no identifier (CamelCase / snake_case >=2 chars), no line number.
+    test: (text) => {
+      if (/[\w./-]+\.\w{1,5}(\b|:)/.test(text)) return false;       // file path
+      if (/:\d+/.test(text)) return false;                           // line number
+      if (/\b(src|lib|app|tests?|spec|docs?)\//i.test(text)) return false; // dir
+      // Identifier: snake_case, UpperCamelCase, or lowerCamelCase (>=2 segments)
+      if (/\b([a-z]+_[a-z][\w_]*|[A-Z][a-z]+[A-Z]\w*|[a-z]+[A-Z]\w*)\b/.test(text)) return false;
+      return true;
+    }
+  },
+  {
+    id: 'scope_plural',
+    test: (text) => /\b(the\s+tests|all\s+the\s+(things|stuff|files)|everything|stuff|things)\b/i.test(text)
+  },
+  {
+    id: 'polysemous',
+    // Bare polysemous coding terms standing alone (no object/qualifier).
+    test: (text) => {
+      const t = text.trim().toLowerCase();
+      return /^(source|build|run|deploy|ship|release|setup|set\s*up)\.?\s*$/.test(t);
+    }
+  },
+  {
+    id: 'missing_constraint',
+    // No constraint terms AND no numeric threshold AND text is non-trivial.
+    test: (text) => {
+      if (text.trim().split(/\s+/).length < 4) return false; // very short = skip rule
+      const hasConstraint = /\b(must|should|when|if|until|without|only|always|never|except)\b/i.test(text);
+      const hasNumber = /\b\d+\b/.test(text);
+      return !hasConstraint && !hasNumber;
+    }
+  }
+];
+
+// Bypass conditions -- match severity1 plugin convention plus IJFW override.
+function bypassReason(text) {
+  if (typeof text !== 'string') return 'non-string';
+  const t = text.trim();
+  if (t.length === 0) return 'empty';
+  if (t.startsWith('*'))  return 'asterisk-prefix';
+  if (t.startsWith('/'))  return 'slash-command';
+  if (t.startsWith('#'))  return 'memorize-prefix';
+  if (/\bijfw\s+off\b/i.test(t)) return 'override-keyword';
+  // Pasted code/stack trace (very long or fenced) -- assume user knows the target.
+  if (t.length > 4000) return 'long-prompt';
+  if (/^```/m.test(t))  return 'fenced-code';
+  return null;
+}
+
+function checkPrompt(text) {
+  const bypass = bypassReason(text);
+  if (bypass) {
+    return { vague: false, signals: [], suggestion: '', bypass_reason: bypass };
+  }
+
+  const tokens = text.trim().split(/\s+/);
+  const signals = [];
+  for (const rule of RULES) {
+    try {
+      if (rule.test(text)) signals.push(rule.id);
+    } catch { /* never break the hook */ }
+  }
+
+  // Fire only when >=2 signals tripped AND prompt is short AND no target found.
+  // Threshold tuned for low false-positive rate per research (UX section).
+  const short = tokens.length < 30;
+  const noTarget = signals.includes('no_target');
+  const vague = signals.length >= 2 && short && noTarget;
+
+  // Positive-framed suggestion. Never says "your prompt is vague."
+  let suggestion = '';
+  if (vague) {
+    if (signals.includes('bare_verb') && noTarget) {
+      suggestion = 'Sharpening your aim -- which file, function, or symbol? e.g. src/auth.py:145, getUserById, the failing test name.';
+    } else if (signals.includes('unresolved_anaphora')) {
+      suggestion = 'Anchoring the reference -- which file or recent code do you mean?';
+    } else {
+      suggestion = 'Pinning the target -- naming the file, symbol, or expected behavior will sharpen the edit.';
+    }
+  }
+
+  // W2.2/A2 -- structured question pack the agent can surface verbatim
+  // when vague. Each question maps to a signal that fired. Keeps to
+  // ≤3 questions (Krug: don't make me answer 10).
+  const rewrite = vague ? buildQuestionPack(signals) : null;
+
+  return { vague, signals, suggestion, rewrite };
+}
+
+// Map signals → clarifying questions, deduped and capped at 3.
+function buildQuestionPack(signals) {
+  const qs = [];
+  const seen = new Set();
+  const add = (q) => { if (!seen.has(q)) { seen.add(q); qs.push(q); } };
+  for (const sig of signals) {
+    if (qs.length >= 3) break;
+    switch (sig) {
+      case 'bare_verb':
+      case 'no_target':
+        add('Which file, function, or line number is the target?');
+        break;
+      case 'unresolved_anaphora':
+        add('What does "this/that" refer to -- a file, a symptom, a prior message?');
+        break;
+      case 'abstract_goal':
+        add('What specifically would "done" look like -- a metric, a test passing, or observable behavior?');
+        break;
+      case 'scope_plural':
+        add('Which of "all the X" -- do you want every instance, or a specific subset?');
+        break;
+      case 'missing_constraint':
+        add('Any constraints I should respect -- don\'t touch X, must run in <Y ms, preserve behavior Z?');
+        break;
+      case 'polysemous':
+        add('Which meaning -- e.g. "deploy" could mean build, release, push, or run locally?');
+        break;
+    }
+  }
+  if (qs.length === 0) {
+    qs.push('What file, function, or acceptance criterion pins the target?');
+  }
+  return qs.slice(0, 3);
+}
+
+export { checkPrompt, RULES, bypassReason, buildQuestionPack };

package/src/ralph-allowlist.js

@@ -0,0 +1,88 @@
+/**
+ * Ralph verify-command allowlist -- Wave 0 F.3
+ * Zero deps, ESM. Used by Phase 4 Ralph loop before executing any shell criterion.
+ */
+
+export const ALLOWLIST = [
+  'grep -q',
+  'npm test --',
+  'pytest',
+  'tsc --noEmit',
+  'node --test',
+  'bash scripts/',
+  'git diff --exit-code',
+  'test -f',
+  'test -d',
+];
+
+export const FORBID_LIST = [
+  'rm',
+  'rmdir',
+  'mv',
+  'cp',
+  'curl',
+  'wget',
+  'fetch',
+  'git push',
+  'git reset --hard',
+  'git clean -f',
+  'git rebase -i',
+  'sudo',
+  'chmod',
+  'chown',
+  'bash -c',
+  'eval',
+  'npm publish',
+  'npm install',
+  'pip install',
+];
+
+/**
+ * Check whether a shell command is safe to run as a Ralph verify step.
+ * Checks forbid list first (any token match), then allowlist (prefix match).
+ *
+ * @param {string} cmd
+ * @returns {{ safe: true } | { safe: false, reason: string }}
+ */
+export function isSafeVerifyCommand(cmd) {
+  if (typeof cmd !== 'string' || cmd.trim() === '') {
+    return { safe: false, reason: 'command is empty or not a string' };
+  }
+
+  const trimmed = cmd.trim();
+
+  // Forbid list: check each entry as a token sequence against the command.
+  // Split on whitespace; check that the forbid token appears as a leading
+  // subsequence of whitespace-delimited tokens (so "rm" matches "rm -rf /"
+  // but not "grep -q 'rm'").
+  for (const forbidden of FORBID_LIST) {
+    const forbidTokens = forbidden.split(/\s+/);
+    const cmdTokens = trimmed.split(/\s+/);
+    let matched = true;
+    for (let i = 0; i < forbidTokens.length; i++) {
+      if (cmdTokens[i] !== forbidTokens[i]) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) {
+      return { safe: false, reason: `${forbidden} is in forbid list` };
+    }
+  }
+
+  // Allowlist: command must start with one of the known safe primitives.
+  // Primitives ending in '/' (like 'bash scripts/') are path-prefix matches --
+  // no trailing space needed since the script name continues the token directly.
+  for (const allowed of ALLOWLIST) {
+    if (trimmed === allowed) return { safe: true };
+    if (allowed.endsWith('/')) {
+      if (trimmed.startsWith(allowed)) return { safe: true };
+    } else {
+      if (trimmed.startsWith(allowed + ' ') || trimmed.startsWith(allowed + '\t')) {
+        return { safe: true };
+      }
+    }
+  }
+
+  return { safe: false, reason: 'no allowlist match' };
+}

package/src/receipts.js

@@ -0,0 +1,129 @@
+// receipts.js -- atomic append/read for cross-run JSONL receipts.
+// ESM, zero deps, synchronous fs.
+//
+// renderReceipt(record, stepNum?) -- human-readable text for one receipt.
+//   Header:  Phase N / Wave NA -- <operation> -- <timestamp>
+//   Body:    Step N.M -- <finding>
+//   cache_stats fields (cache_creation_input_tokens, cache_read_input_tokens)
+//   are rendered when present; absence is a no-op.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function RECEIPTS_FILE(projectDir) {
+  return path.join(projectDir, '.ijfw', 'receipts', 'cross-runs.jsonl');
+}
+
+const MAX_RECEIPTS = 100;
+
+// Atomic append: O_APPEND is atomic for writes ≤ PIPE_BUF (>=4KB on POSIX).
+// One JSON line is well under that limit, so appendFileSync is safe for
+// concurrent writers without a lock or rename dance.
+// After each write, prune to the last MAX_RECEIPTS entries.
+export function writeReceipt(projectDir, record) {
+  const dest = RECEIPTS_FILE(projectDir);
+  const dir = path.dirname(dest);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(dest, JSON.stringify(record) + '\n');
+  _pruneReceipts(dest);
+}
+
+// Keep only the last MAX_RECEIPTS lines. No-op when at or under the limit.
+function _pruneReceipts(dest) {
+  const raw = fs.readFileSync(dest, 'utf8');
+  const lines = raw.split('\n').filter(l => l.trim());
+  if (lines.length <= MAX_RECEIPTS) return;
+  fs.writeFileSync(dest, lines.slice(-MAX_RECEIPTS).join('\n') + '\n');
+}
+
+// Purge all receipts. Returns the count of entries removed.
+export function purgeReceipts(projectDir) {
+  const dest = RECEIPTS_FILE(projectDir);
+  if (!fs.existsSync(dest)) return 0;
+  const raw = fs.readFileSync(dest, 'utf8');
+  const count = raw.split('\n').filter(l => l.trim()).length;
+  fs.writeFileSync(dest, '');
+  return count;
+}
+
+// Anthropic cache-read savings rate (mirrors hero-line.js constant).
+const CACHE_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+
+// renderReceipt(record, phaseWave?, stepNum?)
+//   phaseWave -- caller-supplied label for the narration header. Default is
+//                a generic "Trident" heading so receipts do not carry stale
+//                phase numbers after IJFW itself moves on.
+//   stepNum   -- N.M index for body lines (default 1)
+// Returns a multi-line string. JSONL schema is never modified.
+export function renderReceipt(record, phaseWave = 'Trident', stepNum = 1) {
+  const op = record.mode || 'cross';
+  const ts = record.timestamp ? record.timestamp.slice(0, 19).replace('T', ' ') : '';
+  const lines = [];
+
+  // Header: Phase N / Wave NA -- <operation> -- <timestamp>
+  lines.push(`${phaseWave} -- ${op} -- ${ts}`);
+
+  // Auditors
+  if (Array.isArray(record.auditors) && record.auditors.length > 0) {
+    const ids = record.auditors.map(a => a.id).filter(Boolean).join(', ');
+    lines.push(`Step ${stepNum}.1 -- auditors: ${ids}`);
+  }
+
+  // Findings
+  const findings = record.findings;
+  if (findings) {
+    if (Array.isArray(findings.items)) {
+      lines.push(`Step ${stepNum}.2 -- findings: ${findings.items.length} items`);
+    } else {
+      const c = typeof findings.consensus === 'number' ? findings.consensus : 0;
+      const ct = typeof findings.contested === 'number' ? findings.contested : 0;
+      const u = typeof findings.unique === 'number' ? findings.unique : 0;
+      lines.push(`Step ${stepNum}.2 -- findings: ${c} consensus, ${ct} contested, ${u} unique`);
+    }
+  }
+
+  // Duration
+  if (typeof record.duration_ms === 'number') {
+    const dur = record.duration_ms < 1000
+      ? `${Math.round(record.duration_ms)}ms`
+      : `${Math.round(record.duration_ms / 1000)}s`;
+    lines.push(`Step ${stepNum}.3 -- duration: ${dur}`);
+  }
+
+  // Cache stats (Step 10D.3: rendered when present, no-op when absent)
+  const cs = record.cache_stats;
+  if (cs) {
+    if (cs.cache_eligible === false) {
+      const reason = cs.cache_eligible_reason ?? 'prompt < 1024 tokens';
+      lines.push(`Step ${stepNum}.4 -- cache-eligible: false (${reason})`);
+    } else {
+      if (typeof cs.cache_creation_input_tokens === 'number') {
+        lines.push(`Step ${stepNum}.4 -- cache created: ${cs.cache_creation_input_tokens} tokens`);
+      }
+      if (typeof cs.cache_read_input_tokens === 'number') {
+        const saved = cs.cache_read_input_tokens * CACHE_SAVINGS_PER_TOKEN;
+        const savedStr = saved >= 0.01 ? ` (~$${saved.toFixed(2)} saved)` : '';
+        lines.push(`Step ${stepNum}.5 -- cache read: ${cs.cache_read_input_tokens} tokens${savedStr}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// Read and parse all lines; skip corrupt lines; return array.
+export function readReceipts(projectDir) {
+  const file = RECEIPTS_FILE(projectDir);
+  if (!fs.existsSync(file)) return [];
+  const raw = fs.readFileSync(file, 'utf8');
+  const results = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      results.push(JSON.parse(line));
+    } catch {
+      // skip malformed line
+    }
+  }
+  return results;
+}

package/src/redactor.js

@@ -0,0 +1,107 @@
+// --- Secret redactor (audit S5) ---
+// Strips common credential patterns before any memory write. Conservative
+// by design: pattern list is additive, never tries to classify "suspicious"
+// strings. Better to miss a novel format than to corrupt legitimate prose.
+//
+// Wired into auto-memorize in Wave 3. Exported here so Wave 0 can land the
+// library + tests ahead of the integration.
+
+const PATTERNS = [
+  // Anthropic -- must come BEFORE generic OpenAI so `sk-ant-...` gets labeled correctly.
+  { re: /sk-ant-[A-Za-z0-9_-]{20,}/g,              label: 'anthropic' },
+  // OpenAI -- `sk-proj-...` or `sk-...` with strong minimum length to avoid
+  // eating prose references like "sk-learn" (scikit-learn).
+  { re: /sk-(?:proj-)?[A-Za-z0-9_-]{32,}/g,        label: 'openai'    },
+  // GitHub classic PAT + fine-grained PAT + OAuth/App/User/Refresh tokens.
+  { re: /ghp_[A-Za-z0-9]{20,}/g,                   label: 'github'    },
+  { re: /github_pat_[A-Za-z0-9_]{20,}/g,           label: 'github'    },
+  { re: /gh[ousr]_[A-Za-z0-9]{30,}/g,              label: 'github'    }, // gho_/ghu_/ghs_/ghr_
+  // AWS permanent access key ID (AKIA) + temporary (ASIA) key ID.
+  { re: /(?:AKIA|ASIA)[0-9A-Z]{16}/g,              label: 'aws'       },
+  // Authorization: Bearer <token>.
+  { re: /Bearer\s+[A-Za-z0-9._~+/=-]{10,}/g,       label: 'bearer'    },
+  // Slack bot / user / legacy tokens.
+  { re: /xox[baprs]-[A-Za-z0-9-]{10,}/g,           label: 'slack'     },
+  // Stripe live + test secret keys.
+  { re: /sk_live_[A-Za-z0-9]{24,}/g,               label: 'stripe'    },
+  { re: /sk_test_[A-Za-z0-9]{24,}/g,               label: 'stripe'    },
+  // npm access tokens.
+  { re: /npm_[A-Za-z0-9]{36}/g,                    label: 'npm'       },
+  // HuggingFace user tokens.
+  { re: /hf_[A-Za-z0-9]{34,}/g,                    label: 'huggingface' },
+  // Azure Storage connection-string AccountKey (base64, 88 chars with padding).
+  { re: /AccountKey=[A-Za-z0-9+/]{86,88}={0,2}/g,  label: 'azure'     },
+  // GCP service-account private key PEM block.
+  { re: /-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]+?-----END (?:RSA )?PRIVATE KEY-----/g, label: 'gcp' },
+  // GCP / Google API keys -- `AIza...` (39 chars total).
+  { re: /AIza[0-9A-Za-z_-]{35}/g,                  label: 'gcp'       },
+  // Sentry DSN -- https://<key>@o<org>.ingest.sentry.io/<project>.
+  { re: /https?:\/\/[0-9a-f]{32,}(?::[0-9a-f]{32,})?@[\w.-]*sentry\.io\/[0-9]+/gi, label: 'sentry' },
+  // Cloudflare API tokens (40 chars base64url). Conservative: only flag when
+  // contextualized (CF_API_TOKEN=..., CLOUDFLARE_TOKEN=..., cf_auth_key=...)
+  // so we don't eat bare git commit SHAs or content hashes.
+  { re: /(?:cf|cloudflare)[_-]?(?:api[_-]?)?(?:token|auth|key)s?[= :]+[A-Za-z0-9_-]{40,}/gi, label: 'cloudflare' },
+  // Webhook URLs (Slack, Discord, MS Teams) -- include the secret path segment.
+  { re: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/g, label: 'webhook' },
+  { re: /https:\/\/discord(?:app)?\.com\/api\/webhooks\/\d+\/[A-Za-z0-9_-]+/g,           label: 'webhook' },
+  { re: /https:\/\/[\w-]+\.webhook\.office\.com\/webhookb2\/[\w@/-]+/g,                  label: 'webhook' },
+];
+
+// INLINE rules match `key=value` style assignments. Value regex excludes
+// `[` and `]` so we don't re-redact tokens already labeled by PATTERNS
+// (e.g. `GOOGLE_API_KEY=[REDACTED:gcp]` must stay labeled, not get flattened
+// to `[REDACTED]`).
+const INLINE = [
+  /(password\s*=\s*)[^\s[\]]+/gi,
+  /(api[_-]?token\s*=\s*)[^\s[\]]+/gi,
+  /(api[_-]?key\s*=\s*)[^\s[\]]+/gi,
+  /(secret\s*=\s*)[^\s[\]]+/gi,
+  /(client[_-]?secret\s*=\s*)[^\s[\]]+/gi,
+  // JSON-style "clientSecret": "value" and similar.
+  /("(?:client_?secret|api_?key|password|access_?token)"\s*:\s*")[^"]+(")/gi,
+];
+
+export function redactSecrets(s) {
+  if (typeof s !== 'string' || !s) return '';
+  let out = s;
+  for (const { re, label } of PATTERNS) out = out.replace(re, `[REDACTED:${label}]`);
+  for (const re of INLINE) {
+    if (re.source.startsWith('("')) {
+      // JSON pattern: keep the opening and closing quotes/keys, redact value.
+      out = out.replace(re, '$1[REDACTED]$2');
+    } else {
+      out = out.replace(re, '$1[REDACTED]');
+    }
+  }
+  return out;
+}
+
+// classify(value) -> { clean: boolean, redacted_kind: string | null }
+//
+// D-PILLAR-SPEC section 3 surface used by D2 entity extraction. Passes the
+// value through the same PATTERNS list redactSecrets uses; if any pattern
+// matches the WHOLE value (anchor-equivalent: pattern consumes the entire
+// trimmed string), the value is classified as a secret and `redacted_kind`
+// carries the matched label. INLINE rules are not applied here -- they
+// only fire on key=value assignments which would never reach the entity
+// extractor as a bare entity name.
+//
+// Important: PATTERNS are anchored implicitly via length minimums (e.g.
+// `sk-(?:proj-)?[A-Za-z0-9_-]{32,}`), but to avoid classifying a long file
+// path that happens to contain a token-shaped substring, classify() rejects
+// only when the pattern matches the FULL trimmed value. File paths and
+// function/identifier names are always shorter than the secret patterns'
+// minimum lengths, so the conservative cut-line is "match must equal the
+// candidate" -- a substring match doesn't trigger classification.
+export function classify(value) {
+  if (typeof value !== 'string') return { clean: true, redacted_kind: null };
+  const v = value.trim();
+  if (!v) return { clean: true, redacted_kind: null };
+  for (const { re, label } of PATTERNS) {
+    // Build a fresh non-global RegExp per check; the source PATTERNS use /g
+    // for redactSecrets but classify needs a single full-value match.
+    const r = new RegExp(`^(?:${re.source})$`, re.flags.replace('g', ''));
+    if (r.test(v)) return { clean: false, redacted_kind: label };
+  }
+  return { clean: true, redacted_kind: null };
+}