whynot-cli 0.0.0-stage → 0.1.0

package/src/audit.js

@@ -0,0 +1,222 @@
+// Audit an existing repository for agent rules that are likely to be obeyed
+// long after they stopped being true.
+//
+// This is a heuristic, not a verdict. It looks for the two properties that
+// caused the failure in our experiments: absolute language with no stated
+// condition, and age. It does not call a model, and it never changes files.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const CONFIG_CANDIDATES = [
+  'AGENTS.md',
+  'AGENTS.override.md',
+  'CLAUDE.md',
+  '.claude/CLAUDE.md',
+  'GEMINI.md',
+  '.cursorrules',
+  '.windsurfrules',
+  '.github/copilot-instructions.md',
+];
+
+// Absolute phrasing — the kind of rule that becomes a permanent constraint.
+const ABSOLUTE = [
+  /\bnever\b/i,
+  /\balways\b/i,
+  /\bmust not\b/i,
+  /\bdo not\b/i,
+  /\bdon'?t\b/i,
+  /\bavoid\b/i,
+  /不要/,
+  /不能/,
+  /必须/,
+  /禁止/,
+  /绝不/,
+  /永远/,
+  /一律/,
+  /不允许/,
+];
+
+// Conditional phrasing — the escape hatch that lets a rule expire on its own.
+const CONDITION = [
+  /\bunless\b/i,
+  /\bexcept\b/i,
+  /\bif\b/i,
+  /\bwhen\b/i,
+  /\buntil\b/i,
+  /\bonly (?:if|when)\b/i,
+  /\brevisit\b/i,
+  /除非/,
+  /如果/,
+  /若/,
+  /当/,
+  /直到/,
+  /仅在/,
+  /只有/,
+];
+
+// Instruction words carry no topic. Without this, "never" looks like a theme
+// shared by every rule in the repo.
+const STOPWORDS = new Set([
+  'never', 'always', 'must', 'dont', 'avoid', 'only', 'also', 'just', 'even',
+  'this', 'that', 'these', 'those', 'with', 'from', 'into', 'your', 'their',
+  'there', 'here', 'have', 'has', 'been', 'being', 'when', 'unless', 'except',
+  'until', 'some', 'more', 'than', 'then', 'they', 'them', 'what', 'which',
+  'code', 'file', 'files', 'project', 'repo', 'repository', 'please', 'should',
+  'would', 'could', 'make', 'sure', 'used', 'using', 'need', 'want', 'keep',
+  'every', 'each', 'other', 'into', 'over', 'under', 'about', 'after', 'before',
+]);
+
+/** Topic-ish tokens. Trailing punctuation is stripped so "redis." == "redis". */
+function topicTokens(text) {
+  return [
+    ...new Set(
+      (text.toLowerCase().match(/[a-z][a-z0-9.+#-]{2,}/g) || [])
+        .map((t) => t.replace(/[.+#-]+$/, ''))
+        .filter((t) => t.length >= 4 && !STOPWORDS.has(t))
+    ),
+  ];
+}
+
+function findConfigFiles(root) {
+  const found = [];
+
+  for (const rel of CONFIG_CANDIDATES) {
+    const p = path.join(root, rel);
+    if (fs.existsSync(p) && fs.statSync(p).isFile()) found.push(p);
+  }
+
+  // Directory-style configs.
+  for (const dir of ['.cursor/rules', '.github/instructions']) {
+    const d = path.join(root, dir);
+    if (!fs.existsSync(d) || !fs.statSync(d).isDirectory()) continue;
+    for (const f of fs.readdirSync(d)) {
+      const p = path.join(d, f);
+      if (fs.statSync(p).isFile() && /\.(md|mdc|txt)$/i.test(f)) found.push(p);
+    }
+  }
+
+  return [...new Set(found)];
+}
+
+function lastCommitDaysAgo(root, file, now) {
+  try {
+    const out = execFileSync('git', ['log', '-1', '--format=%ct', '--', path.relative(root, file)], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!out) return null;
+    return Math.floor((now - new Date(Number(out) * 1000)) / 86_400_000);
+  } catch {
+    return null; // not a git repo, or git missing — age unknown
+  }
+}
+
+/** Lines that read like an instruction rather than prose or a heading. */
+function candidateRules(text) {
+  return text
+    .split(/\r?\n/)
+    .map((line, i) => ({ line: line.trim(), number: i + 1 }))
+    .filter(({ line }) => line.length >= 6 && !line.startsWith('#') && !line.startsWith('<!--'))
+    .filter(({ line }) => ABSOLUTE.some((re) => re.test(line)));
+}
+
+export function audit(root, { now = new Date(), staleDays = 365 } = {}) {
+  const files = findConfigFiles(root);
+  const findings = [];
+  const ages = new Map();
+
+  for (const file of files) {
+    const age = lastCommitDaysAgo(root, file, now);
+    ages.set(file, age);
+
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+
+    for (const rule of candidateRules(text)) {
+      const hasCondition = CONDITION.some((re) => re.test(rule.line));
+      const isOld = age !== null && age >= staleDays;
+      if (hasCondition) continue;
+
+      findings.push({
+        file: path.relative(root, file),
+        line: rule.number,
+        text: rule.line.replace(/\s+/g, ' ').slice(0, 140),
+        ageDays: age,
+        reasons: [
+          'absolute rule with no stated condition',
+          ...(isOld ? [`unchanged for ${age} days`] : []),
+        ],
+      });
+    }
+  }
+
+  // Same topic mentioned in several places drifts apart. Cheap proxy: shared
+  // distinctive tokens between rules in different files.
+  const byToken = new Map();
+  for (const f of findings) {
+    for (const token of topicTokens(f.text)) {
+      if (!byToken.has(token)) byToken.set(token, []);
+      byToken.get(token).push(f);
+    }
+  }
+  const duplicated = [...byToken.entries()]
+    .filter(([, hits]) => new Set(hits.map((h) => h.file)).size > 1)
+    .map(([token]) => token);
+
+  return {
+    files: files.map((f) => ({ path: path.relative(root, f), ageDays: ages.get(f) })),
+    findings,
+    duplicatedTokens: [...new Set(duplicated)].slice(0, 10),
+    scanned: files.length,
+  };
+}
+
+/** Human-readable report. Plain text so it can be pasted anywhere. */
+export function renderAudit(report) {
+  const lines = [];
+
+  if (!report.scanned) {
+    lines.push('No agent config files found.');
+    lines.push('Looked for: AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/*, .github/copilot-instructions.md');
+    return lines.join('\n');
+  }
+
+  lines.push(`Scanned ${report.scanned} agent config file${report.scanned === 1 ? '' : 's'}:`);
+  for (const f of report.files) {
+    lines.push(`  ${f.path}${f.ageDays === null ? '' : `  (last changed ${f.ageDays}d ago)`}`);
+  }
+  lines.push('');
+
+  if (!report.findings.length) {
+    lines.push('No unqualified absolute rules found. Nothing to review.');
+    return lines.join('\n');
+  }
+
+  lines.push(`${report.findings.length} rule${report.findings.length === 1 ? '' : 's'} look like permanent constraints:`);
+  lines.push('');
+
+  for (const f of report.findings.slice(0, 20)) {
+    lines.push(`  ${f.file}:${f.line}`);
+    lines.push(`    "${f.text}"`);
+    lines.push(`    → ${f.reasons.join('; ')}`);
+  }
+  if (report.findings.length > 20) lines.push(`  ... and ${report.findings.length - 20} more`);
+
+  if (report.duplicatedTokens.length) {
+    lines.push('');
+    lines.push(`Topics mentioned across more than one file (may have drifted): ${report.duplicatedTokens.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push('These are heuristics, not errors. A rule with no condition is fine —');
+  lines.push('until nobody remembers why it exists. whynot turns those into entries');
+  lines.push('that expire unless someone renews them.');
+  return lines.join('\n');
+}

package/src/cli.js

@@ -0,0 +1,293 @@
+// CLI: the human half of the loop. Agents get the MCP server; people get this.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  findRoot,
+  init,
+  create,
+  retire,
+  renew,
+  check,
+  stale,
+  readAll,
+  summarize,
+  render,
+  expiresOn,
+  daysUntilExpiry,
+  DIR_NAME,
+  TYPES,
+} from './store.js';
+import { audit, renderAudit } from './audit.js';
+import { serve } from './mcp.js';
+
+const USAGE = `whynot — record what you ruled out, and why
+
+Usage:
+  whynot init                     Create ${DIR_NAME}/ and the .gitattributes rule
+  whynot add --title T --why W    Record an entry
+        [--type rejected|decision|constraint]
+        [--revisit "condition"]   When to reconsider
+        [--ttl N]                 Days until it expires (default: rejected 90,
+                                  decision 180, constraint 365)
+        [--expires never]         Explicitly permanent
+        [--evidence pr:412]       Repeatable
+        [--tags infra,session]
+  whynot list [--all]             List live entries (--all includes retired)
+  whynot check "<query>"          Show live entries matching a query
+  whynot stale                    Entries needing a human decision (expired first)
+  whynot renew <id> [--days N]    Extend an entry's life
+  whynot retire <id>              Mark an entry retired (never deletes)
+  whynot doctor                   Validate the store
+  whynot audit [--days N]         Scan AGENTS.md / CLAUDE.md for rules that
+                                  will be obeyed forever (read-only)
+  whynot mcp                      Run the MCP server on stdio (used by agents)
+
+An entry that expires stops being shown to your agent until you renew it.
+That is deliberate: see VALIDATION.md for why.
+
+Options:
+  --root <dir>   Operate on this repo instead of searching upward from cwd
+  -h, --help     Show this message
+`;
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) {
+      positional.push(a);
+      continue;
+    }
+    const eq = a.indexOf('=');
+    if (eq !== -1) {
+      const key = a.slice(2, eq);
+      (flags[key] ??= []).push(a.slice(eq + 1));
+    } else {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        (flags[key] ??= []).push(next);
+        i++;
+      } else {
+        (flags[key] ??= []).push(true);
+      }
+    }
+  }
+
+  const one = (k) => (Array.isArray(flags[k]) ? flags[k][flags[k].length - 1] : undefined);
+  return { flags, positional, one };
+}
+
+function resolveRoot(one) {
+  const explicit = one('root');
+  if (explicit && explicit !== true) return path.resolve(explicit);
+  const found = findRoot(process.cwd());
+  if (!found) {
+    throw new Error(
+      `No ${DIR_NAME}/ found from ${process.cwd()} upward. Run \`whynot init\` first, or pass --root.`
+    );
+  }
+  return found;
+}
+
+const out = (s = '') => process.stdout.write(s + '\n');
+const err = (s) => process.stderr.write(s + '\n');
+
+export function run(argv = process.argv.slice(2)) {
+  const command = argv[0];
+  const { flags, positional, one } = parseArgs(argv.slice(1));
+
+  if (!command || command === '-h' || command === '--help' || one('help')) {
+    out(USAGE);
+    return 0;
+  }
+
+  switch (command) {
+    case 'init': {
+      const root = one('root') && one('root') !== true ? path.resolve(one('root')) : process.cwd();
+      const { dir } = init(root);
+      out(`Initialized ${path.relative(process.cwd(), dir) || dir}`);
+      out('Added "*.md text eol=lf" to .gitattributes');
+      out('');
+      out('Next: add the whynot block to your AGENTS.md (see AGENTS.snippet.md),');
+      out('and register the MCP server with your agent.');
+      return 0;
+    }
+
+    case 'add': {
+      const root = resolveRoot(one);
+      const title = one('title');
+      const why = one('why');
+      if (!title || title === true) throw new Error('--title is required');
+      if (!why || why === true) throw new Error('--why is required');
+
+      const type = one('type') || 'rejected';
+      const ttlRaw = one('ttl');
+      const ttl = ttlRaw && ttlRaw !== true ? parseInt(ttlRaw, 10) : undefined;
+      const expiresRaw = one('expires');
+
+      const created = create(root, {
+        title,
+        type,
+        revisit_when: one('revisit') === true ? undefined : one('revisit'),
+        ttl_days: Number.isFinite(ttl) ? ttl : undefined,
+        expires_on: expiresRaw && expiresRaw !== true ? expiresRaw : undefined,
+        evidence: (flags.evidence || []).filter((e) => e !== true),
+        tags: (one('tags') || '')
+          .toString()
+          .split(',')
+          .map((t) => t.trim())
+          .filter(Boolean),
+        body: `## 为什么\n\n${why}\n`,
+      });
+
+      const [saved] = readAll(root).filter((e) => e.id === created.id);
+      const left = daysUntilExpiry(saved);
+      out(`Recorded [${created.id}] ${created.filename}`);
+      out(
+        left === null
+          ? '  Expires: never (explicitly permanent)'
+          : `  Expires: ${expiresOn(saved)} (in ${left} days) — renew with \`whynot renew ${created.id}\``
+      );
+      return 0;
+    }
+
+    case 'list': {
+      const root = resolveRoot(one);
+      const all = Boolean(one('all'));
+      const entries = readAll(root).filter((e) => all || e.status === 'live');
+      if (!entries.length) {
+        out(`No entries. (\`whynot add\` to record one, \`whynot list --all\` to include retired.)`);
+        return 0;
+      }
+      for (const e of entries) {
+        const tag = e.status === 'retired' ? ' [retired]' : '';
+        out(summarize(e) + tag);
+      }
+      out('');
+      out(`${entries.length} entr${entries.length === 1 ? 'y' : 'ies'}`);
+      return 0;
+    }
+
+    case 'check': {
+      const root = resolveRoot(one);
+      const query = positional.join(' ');
+      const found = check(root, { query, tags: one('tags') ? one('tags').split(',') : [] });
+      if (!found.length) {
+        out(query ? `Nothing recorded matching "${query}".` : 'No live entries.');
+        return 0;
+      }
+      out(found.map(render).join('\n\n---\n\n'));
+      return 0;
+    }
+
+    case 'stale': {
+      const root = resolveRoot(one);
+      const found = stale(root);
+      if (!found.length) {
+        out('Nothing needs review.');
+        return 0;
+      }
+      for (const e of found) {
+        out(`${summarize(e)}\n    ${e.reasons.join('\n    ')}`);
+      }
+      out('');
+      out(
+        `${found.length} to review.\n` +
+          '  `whynot renew <id>`  — it still holds, extend it\n' +
+          '  `whynot retire <id>` — it no longer holds, archive it'
+      );
+      return 0;
+    }
+
+    case 'renew': {
+      const root = resolveRoot(one);
+      const id = positional[0];
+      if (!id) throw new Error('usage: whynot renew <id> [--days N]');
+      const days = parseInt(one('days'), 10);
+      const done = renew(root, id, { days: Number.isFinite(days) ? days : null });
+      out(`Renewed [${done.id}] — now expires ${done.expires_on}.`);
+      return 0;
+    }
+
+    case 'retire': {
+      const root = resolveRoot(one);
+      const id = positional[0];
+      if (!id) throw new Error('usage: whynot retire <id>');
+      const done = retire(root, id);
+      out(`Retired [${done.id}]. The file is kept, not deleted.`);
+      return 0;
+    }
+
+    case 'audit': {
+      const explicit = one('root');
+      const root = explicit && explicit !== true ? path.resolve(explicit) : process.cwd();
+      const days = parseInt(one('days'), 10);
+      const report = audit(root, { staleDays: Number.isFinite(days) ? days : 365 });
+      out(renderAudit(report));
+      return 0;
+    }
+
+    case 'mcp': {
+      // Blocks on stdin for the life of the process. This is the entry point
+      // the documented MCP config uses: `npx -y whynot mcp`.
+      serve();
+      return 0;
+    }
+
+    case 'doctor': {
+      const root = resolveRoot(one);
+      const entries = readAll(root);
+      const problems = [];
+
+      const seen = new Map();
+      for (const e of entries) {
+        if (!e.id) problems.push(`${e.filename}: missing id`);
+        if (!e.title) problems.push(`${e.filename}: missing title`);
+        if (!TYPES.includes(e.type)) problems.push(`${e.filename}: unknown type "${e.type}"`);
+        if (e.id) {
+          if (seen.has(e.id)) problems.push(`duplicate id ${e.id}: ${seen.get(e.id)} and ${e.filename}`);
+          else seen.set(e.id, e.filename);
+        }
+        const expected = e.id && e.title ? `${e.id}-` : null;
+        if (expected && !e.filename.startsWith(expected)) {
+          problems.push(`${e.filename}: filename does not start with its id (${e.id})`);
+        }
+      }
+
+      // Retired entries with no retirement date are almost always a hand-edit.
+      for (const e of entries) {
+        if (e.status === 'retired' && !e.retired_on) {
+          problems.push(`${e.filename}: retired but no retired_on date`);
+        }
+      }
+
+      out(`${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} in ${path.join(root, DIR_NAME)}`);
+      if (!problems.length) {
+        out('No problems found.');
+        return 0;
+      }
+      out('');
+      for (const p of problems) out(`  ! ${p}`);
+      return 1;
+    }
+
+    default:
+      err(`Unknown command: ${command}`);
+      err('');
+      err(USAGE);
+      return 2;
+  }
+}
+
+export function main() {
+  try {
+    process.exitCode = run();
+  } catch (e) {
+    err(`error: ${e.message}`);
+    process.exitCode = 1;
+  }
+}

package/src/frontmatter.js

@@ -0,0 +1,128 @@
+// Minimal YAML-subset frontmatter parser.
+//
+// Deliberately NOT a general YAML parser. It handles exactly the shapes whynot
+// emits, so there is no dependency to rot and no surprising parse results:
+//
+//   key: scalar
+//   key: "quoted scalar"
+//   key: [a, b, c]
+//   key:
+//     - item
+//
+// Anything it does not understand is ignored rather than throwing, because a
+// malformed decision file should never break an agent's session.
+
+const DELIM = '---';
+
+function unquote(s) {
+  if (s.length >= 2) {
+    const first = s[0];
+    const last = s[s.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return s.slice(1, -1);
+    }
+  }
+  return s;
+}
+
+/** Needs quoting if it could be misread as a list, comment, or empty. */
+function needsQuote(s) {
+  return s === '' || /^[\s[\]{}#&*!|>'"%@`-]/.test(s) || /:\s/.test(s) || s !== s.trim();
+}
+
+function quote(s) {
+  return needsQuote(s) ? JSON.stringify(s) : s;
+}
+
+export function parse(text) {
+  const lines = String(text).split(/\r?\n/);
+  if ((lines[0] || '').trim() !== DELIM) {
+    return { data: {}, body: String(text) };
+  }
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === DELIM) {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) return { data: {}, body: String(text) };
+
+  const data = {};
+  let pendingListKey = null;
+
+  for (let i = 1; i < end; i++) {
+    const raw = lines[i];
+    if (!raw.trim() || raw.trim().startsWith('#')) continue;
+
+    const listItem = raw.match(/^\s+-\s+(.*)$/);
+    if (listItem && pendingListKey) {
+      data[pendingListKey].push(unquote(listItem[1].trim()));
+      continue;
+    }
+
+    const kv = raw.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!kv) continue;
+
+    const key = kv[1];
+    const value = kv[2].trim();
+
+    if (value === '') {
+      data[key] = [];
+      pendingListKey = key;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      data[key] = value
+        .slice(1, -1)
+        .split(',')
+        .map((s) => unquote(s.trim()))
+        .filter(Boolean);
+      pendingListKey = null;
+    } else {
+      data[key] = unquote(value);
+      pendingListKey = null;
+    }
+  }
+
+  // A key declared with no value and no list items becomes '' rather than [],
+  // so consumers can treat "unset scalar" and "unset list" uniformly.
+  for (const k of Object.keys(data)) {
+    if (Array.isArray(data[k]) && data[k].length === 0) data[k] = '';
+  }
+
+  const body = lines
+    .slice(end + 1)
+    .join('\n')
+    .replace(/^\n+/, '');
+
+  return { data, body };
+}
+
+export function stringify(data, body = '') {
+  const out = [DELIM];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined || value === null) continue;
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        out.push(`${key}: []`);
+      } else {
+        out.push(`${key}:`);
+        for (const item of value) out.push(`  - ${quote(String(item))}`);
+      }
+    } else if (typeof value === 'boolean' || typeof value === 'number') {
+      out.push(`${key}: ${value}`);
+    } else {
+      out.push(`${key}: ${quote(String(value))}`);
+    }
+  }
+
+  out.push(DELIM);
+  if (body) {
+    out.push('');
+    out.push(body.replace(/\s+$/, ''));
+  }
+  out.push('');
+  return out.join('\n');
+}

package/src/index.js

@@ -0,0 +1,34 @@
+// Public API.
+//
+// `import { create, check } from 'whynot'` gives you the store. The MCP server
+// and the CLI are separate entry points; they are not part of this surface.
+//
+// Everything here is synchronous and filesystem-backed. There is no client, no
+// connection, and no state beyond the files in the repository.
+
+export {
+  // Layout
+  findRoot,
+  DIR_NAME,
+  TYPES,
+  // Write
+  init,
+  create,
+  retire,
+  renew,
+  // Read
+  readAll,
+  check,
+  listIndex,
+  stale,
+  render,
+  summarize,
+  // Expiry
+  expiresOn,
+  isExpired,
+  daysUntilExpiry,
+  DEFAULT_TTL_DAYS,
+  NEVER,
+} from './store.js';
+
+export { audit, renderAudit } from './audit.js';