kushi-agents 5.2.0 → 5.3.0

package/src/global-wiki.mjs

@@ -0,0 +1,503 @@
+// kushi v5.3.0 — global wiki + promote operation
+//
+// Implements:
+//   - resolveGlobalRoot() — honors $KUSHI_GLOBAL_ROOT
+//   - globalInit() — idempotent scaffold
+//   - globalStatus() — page counts + freshness
+//   - globalAsk() — search global answers/
+//   - globalLint() — lint global wiki (potential-customer-leak + standard classes)
+//   - detectIdentifiers() — privacy scan reused by promote
+//   - promote() — full project→global flow with redaction gate
+//
+// All filesystem mutation must be confined to the resolved global root or the
+// supplied project root. Tests use $env:KUSHI_GLOBAL_ROOT='.testtmp/.kushi-global'
+// — never the real ~/.kushi-global/.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const SCAFFOLD_FILES = {
+  'index.md': `---
+kushi_state_page: true
+scope: global
+---
+
+# Global wiki — index
+
+This is your personal cross-engagement knowledge base. It lives at the path
+resolved by \`$KUSHI_GLOBAL_ROOT\` (or \`~/.kushi-global/State/\` by default)
+and is structurally identical to a project \`State/\` wiki.
+
+Pages are added here by **explicit promotion only** — run
+\`kushi promote <project> <page-path>\` to move a curated page from a project's
+State/ into this global wiki. Auto-promotion is not supported on purpose.
+
+## Sections
+
+- [log.md](log.md) — reverse-chronological op log
+- [conventions.md](conventions.md) — cross-engagement conventions
+- [answers/](answers/) — promoted Q&A pages
+- [reports/](reports/) — lint + status snapshots
+- [_review-queue.md](_review-queue.md) — open privacy / contradiction items
+
+## See also
+
+- \`plugin/instructions/global-wiki.instructions.md\`
+- \`plugin/instructions/multi-wiki-routing.instructions.md\`
+`,
+  'log.md': `---
+kushi_state_page: true
+scope: global
+---
+
+# Global wiki — log
+
+Reverse-chronological. Same format as project \`log.md\`
+(per \`log-format.instructions.md\`). Ops: \`global-init\`, \`promote-in\`,
+\`global-lint\`, \`global-ask-fileback\`.
+`,
+  'conventions.md': `---
+kushi_state_page: true
+scope: global
+---
+
+# Global conventions
+
+Cross-engagement conventions you want kushi to apply across every project.
+This is the \`scope: global\` analog of the per-project \`CLAUDE.md\`.
+v5.3.0 documents the placeholder; runtime application across projects is
+deferred to a future release (v5.4+).
+`,
+  '_review-queue.md': `---
+kushi_state_page: true
+scope: global
+---
+
+# Global review queue
+
+Open items that need your attention. Populated by:
+
+- \`kushi promote\` when it inserts \`[!warning] potential-customer-leak\` callouts.
+- \`kushi global lint\` when it flags contradictions or stale claims.
+`,
+};
+
+const SCAFFOLD_DIRS = ['answers', 'reports'];
+
+// ───────────────────────────────────────────────────────────────────────────
+// Resolution
+
+export function resolveGlobalRoot(env = process.env) {
+  const override = env.KUSHI_GLOBAL_ROOT;
+  if (override && override.trim()) {
+    return path.resolve(expandTilde(override.trim(), env));
+  }
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.kushi-global');
+}
+
+function expandTilde(p, env) {
+  if (p.startsWith('~')) {
+    const home = env.USERPROFILE || env.HOME || os.homedir();
+    return path.join(home, p.slice(1).replace(/^[\\/]/, ''));
+  }
+  return p;
+}
+
+function stateDir(root) {
+  return path.join(root, 'State');
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Init
+
+export function globalInit({ root, now = new Date() } = {}) {
+  const globalRoot = root || resolveGlobalRoot();
+  const state = stateDir(globalRoot);
+  fs.mkdirSync(state, { recursive: true });
+
+  const created = [];
+  const skipped = [];
+
+  for (const dir of SCAFFOLD_DIRS) {
+    const d = path.join(state, dir);
+    if (!fs.existsSync(d)) {
+      fs.mkdirSync(d, { recursive: true });
+      created.push(`${dir}/`);
+    } else {
+      skipped.push(`${dir}/`);
+    }
+  }
+
+  for (const [name, body] of Object.entries(SCAFFOLD_FILES)) {
+    const f = path.join(state, name);
+    if (!fs.existsSync(f)) {
+      fs.writeFileSync(f, body);
+      created.push(name);
+    } else {
+      skipped.push(name);
+    }
+  }
+
+  appendLog(state, 'global-init', `Scaffold checked (${created.length} created, ${skipped.length} already present)`, now);
+
+  return { root: globalRoot, state, created, skipped };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Status
+
+export function globalStatus({ root } = {}) {
+  const globalRoot = root || resolveGlobalRoot();
+  const state = stateDir(globalRoot);
+  if (!fs.existsSync(state)) {
+    return { root: globalRoot, state, initialized: false };
+  }
+  const counts = {
+    pages: 0,
+    answers: 0,
+    reports: 0,
+    review_items: 0,
+  };
+  let newest = 0;
+  walk(state, (full, rel) => {
+    if (!rel.endsWith('.md')) return;
+    counts.pages += 1;
+    if (rel.startsWith('answers' + path.sep) || rel.startsWith('answers/')) counts.answers += 1;
+    if (rel.startsWith('reports' + path.sep) || rel.startsWith('reports/')) counts.reports += 1;
+    const stat = fs.statSync(full);
+    if (stat.mtimeMs > newest) newest = stat.mtimeMs;
+  });
+  const reviewPath = path.join(state, '_review-queue.md');
+  if (fs.existsSync(reviewPath)) {
+    const body = fs.readFileSync(reviewPath, 'utf8');
+    counts.review_items = (body.match(/^- \[ \]/gm) || []).length;
+  }
+  return {
+    root: globalRoot,
+    state,
+    initialized: true,
+    counts,
+    newest_iso: newest ? new Date(newest).toISOString() : null,
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Ask
+
+export function globalAsk({ root, question } = {}) {
+  if (!question || !question.trim()) {
+    return { hits: [], message: 'no question provided' };
+  }
+  const globalRoot = root || resolveGlobalRoot();
+  const answers = path.join(stateDir(globalRoot), 'answers');
+  if (!fs.existsSync(answers)) {
+    return { hits: [], message: 'global wiki not initialized — run `kushi global init`' };
+  }
+
+  const terms = question
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 3);
+  const hits = [];
+  for (const name of fs.readdirSync(answers)) {
+    if (!name.endsWith('.md')) continue;
+    const full = path.join(answers, name);
+    const body = fs.readFileSync(full, 'utf8').toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+      if (body.includes(t)) score += 1;
+    }
+    if (score > 0) {
+      hits.push({ file: full, name, score, provenance: '[global]' });
+    }
+  }
+  hits.sort((a, b) => b.score - a.score);
+  return { hits, message: hits.length ? `${hits.length} match(es)` : 'no matches in global wiki' };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Lint
+
+export function globalLint({ root } = {}) {
+  const globalRoot = root || resolveGlobalRoot();
+  const state = stateDir(globalRoot);
+  if (!fs.existsSync(state)) {
+    return { initialized: false, findings: [] };
+  }
+  const findings = [];
+  walk(state, (full, rel) => {
+    if (!rel.endsWith('.md')) return;
+    const lines = fs.readFileSync(full, 'utf8').split(/\r?\n/);
+    lines.forEach((line, i) => {
+      if (/^>\s*\[!warning\]\s+potential-customer-leak/i.test(line)) {
+        findings.push({
+          class: 'potential-customer-leak',
+          severity: 'warning',
+          file: rel,
+          line: i + 1,
+          snippet: line.trim(),
+          fix: 'Resolve the redaction (rewrite the surrounding sentence) and remove the callout.',
+        });
+      }
+      if (/^>\s*\[!warning\]\s+Contradicted/i.test(line)) {
+        findings.push({
+          class: 'contradiction-flagged',
+          severity: 'warning',
+          file: rel,
+          line: i + 1,
+          snippet: line.trim(),
+          fix: 'Reconcile the contradiction per living-wiki.instructions.md.',
+        });
+      }
+    });
+  });
+  return { initialized: true, findings };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Identifier detection (reused from schema-evolve-style heuristics)
+
+export function detectIdentifiers(body, { project, alias, extraAliases = [] } = {}) {
+  const hits = [];
+  const lines = body.split(/\r?\n/);
+
+  const literals = new Set();
+  if (project) literals.add(project);
+  if (alias) literals.add(alias);
+  for (const x of extraAliases) if (x) literals.add(x);
+
+  for (const lit of literals) {
+    if (!lit || lit.length < 2) continue;
+    const re = new RegExp(`\\b${escapeRegex(lit)}\\b`, 'gi');
+    const lineNumbers = [];
+    lines.forEach((ln, i) => {
+      if (re.test(ln)) lineNumbers.push(i + 1);
+      re.lastIndex = 0;
+    });
+    if (lineNumbers.length) {
+      hits.push({ pattern: lit, kind: 'project-or-alias', count: lineNumbers.length, line_numbers: lineNumbers });
+    }
+  }
+
+  // Non-Microsoft email addresses
+  const emailRe = /\b[A-Za-z0-9._%+-]+@([A-Za-z0-9.-]+\.[A-Za-z]{2,})\b/g;
+  const emailHits = new Map();
+  lines.forEach((ln, i) => {
+    let m;
+    while ((m = emailRe.exec(ln)) !== null) {
+      const domain = m[1].toLowerCase();
+      if (domain.endsWith('microsoft.com') || domain.endsWith('@microsoft.com')) continue;
+      const addr = m[0];
+      if (!emailHits.has(addr)) emailHits.set(addr, []);
+      emailHits.get(addr).push(i + 1);
+    }
+  });
+  for (const [addr, nums] of emailHits) {
+    hits.push({ pattern: addr, kind: 'external-email', count: nums.length, line_numbers: nums });
+  }
+
+  return hits;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Promote
+
+export function promote({
+  project,
+  alias,
+  sourcePath,
+  projectRoot,
+  globalRoot,
+  force = false,
+  extraAliases = [],
+  now = new Date(),
+} = {}) {
+  if (!project || !sourcePath || !projectRoot) {
+    throw new Error('promote: project, sourcePath, projectRoot are required');
+  }
+  const resolvedGlobal = globalRoot || resolveGlobalRoot();
+  const globalState = stateDir(resolvedGlobal);
+
+  // 1. Resolve source.
+  const absSource = path.isAbsolute(sourcePath) ? sourcePath : path.join(projectRoot, sourcePath);
+  if (!fs.existsSync(absSource)) {
+    throw new Error(`promote: source page not found: ${absSource}`);
+  }
+  const sourceBody = fs.readFileSync(absSource, 'utf8');
+
+  // 2. Identifier scan.
+  const aliasFromPath = alias || guessAliasFromPath(absSource, projectRoot);
+  const detections = detectIdentifiers(sourceBody, {
+    project,
+    alias: aliasFromPath,
+    extraAliases,
+  });
+
+  // 3. Refuse without --force.
+  if (detections.length > 0 && !force) {
+    return {
+      ok: false,
+      refused: true,
+      reason: 'identifier-detected',
+      detections,
+      hint: 'Re-run with --force after reviewing the redactions list.',
+    };
+  }
+
+  // 4. Build redacted body.
+  let redactedBody = sourceBody;
+  const redactionLabels = [];
+  for (const d of detections) {
+    const re = new RegExp(`\\b${escapeRegex(d.pattern)}\\b`, 'gi');
+    redactedBody = redactedBody.replace(re, '[REDACTED]');
+    redactionLabels.push(d.pattern);
+  }
+
+  // Strip any existing top-level frontmatter; we replace it.
+  const fmStripped = redactedBody.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+
+  // 5. Compute slug + target path.
+  const sourceFileName = path.basename(absSource, '.md');
+  const slug = slugify(sourceFileName);
+  fs.mkdirSync(path.join(globalState, 'answers'), { recursive: true });
+  let targetName = `${slug}.md`;
+  let targetPath = path.join(globalState, 'answers', targetName);
+  let counter = 1;
+  while (fs.existsSync(targetPath)) {
+    targetName = `${slug}-${counter}.md`;
+    targetPath = path.join(globalState, 'answers', targetName);
+    counter += 1;
+  }
+
+  // 6. Write target with frontmatter.
+  const iso = now.toISOString();
+  const relSource = path.relative(projectRoot, absSource).replace(/\\/g, '/');
+  const promotedFrom = `${project}/${relSource}`;
+  const fm = [
+    '---',
+    'kushi_state_page: true',
+    'scope: global',
+    `promoted_from: "${promotedFrom}"`,
+    `promoted_at: "${iso}"`,
+    `redactions: [${redactionLabels.map((r) => JSON.stringify(r)).join(', ')}]`,
+    '---',
+    '',
+  ].join('\n');
+
+  let finalBody = fm + fmStripped;
+  if (redactionLabels.length > 0) {
+    const callout = [
+      '',
+      '> [!warning] potential-customer-leak',
+      `> This page was promoted with ${redactionLabels.length} redaction(s): ${redactionLabels.map((r) => `\`${r}\``).join(', ')}.`,
+      '> Review the [REDACTED] sites and rewrite surrounding context before sharing.',
+      '',
+    ].join('\n');
+    finalBody = finalBody.trimEnd() + '\n' + callout;
+  }
+  fs.writeFileSync(targetPath, finalBody);
+
+  // 7. Back-link in source.
+  const backLink = [
+    '',
+    '> [!info] Promoted to global wiki',
+    `> answers/${targetName} @ ${iso} · redactions: ${redactionLabels.length}`,
+    '',
+  ].join('\n');
+  // Avoid duplicate back-links if rerun: only append if not already present.
+  const sourceUpdated = sourceBody.includes(`answers/${targetName}`)
+    ? sourceBody
+    : sourceBody.trimEnd() + '\n' + backLink;
+  fs.writeFileSync(absSource, sourceUpdated);
+
+  // 8. Dual log.
+  appendLog(
+    findOrCreateProjectStateDir(absSource),
+    'promote',
+    `Promoted ${slug} to global (redactions: ${redactionLabels.length})`,
+    now,
+  );
+  fs.mkdirSync(globalState, { recursive: true });
+  appendLog(globalState, 'promote-in', `Imported ${slug} from ${project} (redactions: ${redactionLabels.length})`, now);
+
+  return {
+    ok: true,
+    refused: false,
+    detections,
+    redactions: redactionLabels,
+    target: targetPath,
+    source: absSource,
+    slug,
+    promoted_at: iso,
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// helpers
+
+function appendLog(stateRoot, op, title, now) {
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const logFile = path.join(stateRoot, 'log.md');
+  const stamp = now.toISOString().slice(0, 16).replace('T', ' ');
+  const entry = `\n## [${stamp}] ${op} | ${title}\n`;
+  if (!fs.existsSync(logFile)) {
+    fs.writeFileSync(
+      logFile,
+      `---\nkushi_state_page: true\n${stateRoot.includes('.kushi-global') ? 'scope: global\n' : ''}---\n\n# log\n${entry}`,
+    );
+  } else {
+    const existing = fs.readFileSync(logFile, 'utf8');
+    // Insert after first heading (newest-first).
+    const headingMatch = existing.match(/^#\s.+$/m);
+    if (headingMatch) {
+      const idx = existing.indexOf(headingMatch[0]) + headingMatch[0].length;
+      fs.writeFileSync(logFile, existing.slice(0, idx) + entry + existing.slice(idx));
+    } else {
+      fs.writeFileSync(logFile, existing + entry);
+    }
+  }
+}
+
+function slugify(s) {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'page';
+}
+
+function guessAliasFromPath(absSource, projectRoot) {
+  const rel = path.relative(projectRoot, absSource).split(/[\\/]/);
+  const evidIdx = rel.indexOf('Evidence');
+  if (evidIdx !== -1 && rel.length > evidIdx + 1) return rel[evidIdx + 1];
+  return null;
+}
+
+function findOrCreateProjectStateDir(absSource) {
+  // Walk up looking for a directory whose basename is "State".
+  let dir = path.dirname(absSource);
+  while (dir && path.dirname(dir) !== dir) {
+    if (path.basename(dir) === 'State') return dir;
+    dir = path.dirname(dir);
+  }
+  // Fallback: same directory as the source.
+  return path.dirname(absSource);
+}
+
+function walk(root, visit) {
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const full = path.join(root, entry.name);
+    const rel = path.relative(root, full);
+    if (entry.isDirectory()) {
+      walk(full, (f, r) => visit(f, path.join(rel, r)));
+    } else {
+      visit(full, rel);
+    }
+  }
+}

package/src/global-wiki.test.mjs

@@ -0,0 +1,135 @@
+// kushi v5.3.0 — global wiki core tests.
+// MUST use $env:KUSHI_GLOBAL_ROOT pointing under .testtmp/ — never the real ~/.kushi-global/.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import {
+  resolveGlobalRoot,
+  globalInit,
+  globalStatus,
+  globalAsk,
+  globalLint,
+} from './global-wiki.mjs';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const TESTTMP = path.join(repoRoot, '.testtmp');
+
+function freshRoot(label) {
+  const root = path.join(TESTTMP, `global-wiki-${label}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  fs.mkdirSync(root, { recursive: true });
+  return root;
+}
+
+function rmrf(p) {
+  if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+}
+
+test('global-wiki: KUSHI_GLOBAL_ROOT env override is honored', () => {
+  const override = path.join(TESTTMP, 'global-wiki-env-override');
+  const result = resolveGlobalRoot({ KUSHI_GLOBAL_ROOT: override });
+  assert.equal(path.resolve(result), path.resolve(override), 'env override must win over ~/.kushi-global');
+
+  // Sanity: real homedir path must NOT match when override is set.
+  const real = resolveGlobalRoot({});
+  assert.notEqual(path.resolve(result), path.resolve(real), 'override must differ from real default');
+  // And default must point under the home directory.
+  const home = process.env.USERPROFILE || process.env.HOME || os.homedir();
+  assert.ok(real.startsWith(home), 'default must live under user home');
+});
+
+test('global-wiki: init scaffolds the Karpathy shape with scope: global frontmatter', () => {
+  const root = freshRoot('init');
+  try {
+    const result = globalInit({ root });
+    const state = path.join(root, 'State');
+
+    // Files
+    for (const f of ['index.md', 'log.md', 'conventions.md', '_review-queue.md']) {
+      assert.ok(fs.existsSync(path.join(state, f)), `must create State/${f}`);
+      const body = fs.readFileSync(path.join(state, f), 'utf8');
+      assert.match(body, /^---\nkushi_state_page: true\nscope: global\n---/, `${f} must have scope: global frontmatter`);
+    }
+    // Dirs
+    for (const d of ['answers', 'reports']) {
+      assert.ok(fs.existsSync(path.join(state, d)) && fs.statSync(path.join(state, d)).isDirectory(), `must create State/${d}/`);
+    }
+    // Returned shape
+    assert.equal(result.root, root);
+    assert.ok(result.created.length > 0, 'first run must report created entries');
+
+    // Idempotent: second run creates nothing new.
+    const second = globalInit({ root });
+    assert.equal(second.created.length, 0, 'second init must be no-op');
+    assert.ok(second.skipped.length > 0, 'second init must report skipped entries');
+
+    // log.md must have a global-init entry
+    const log = fs.readFileSync(path.join(state, 'log.md'), 'utf8');
+    assert.match(log, /global-init/, 'log must record global-init op');
+  } finally {
+    rmrf(root);
+  }
+});
+
+test('global-wiki: status reports counts after init', () => {
+  const root = freshRoot('status');
+  try {
+    // Pre-init: not initialized.
+    const pre = globalStatus({ root });
+    assert.equal(pre.initialized, false, 'pre-init status must report initialized=false');
+
+    globalInit({ root });
+    const post = globalStatus({ root });
+    assert.equal(post.initialized, true, 'post-init must report initialized=true');
+    assert.ok(typeof post.counts === 'object', 'must return counts');
+    assert.ok(post.counts.pages >= 4, `must count ≥4 pages (index, log, conventions, _review-queue); got ${post.counts.pages}`);
+  } finally {
+    rmrf(root);
+  }
+});
+
+test('global-wiki: ask searches answers/ and returns hits with [global] provenance', () => {
+  const root = freshRoot('ask');
+  try {
+    globalInit({ root });
+    const answers = path.join(root, 'State', 'answers');
+    fs.writeFileSync(
+      path.join(answers, 'confidence-ladder.md'),
+      '---\nkushi_state_page: true\nscope: global\n---\n\n# Confidence ladder\n\nUse strong / weak / hypothesis tiers when reporting findings.\n',
+    );
+
+    const hit = globalAsk({ root, question: 'what is the confidence ladder?' });
+    assert.ok(hit.hits.length >= 1, 'must find the seeded answer page');
+    assert.equal(hit.hits[0].provenance, '[global]', 'provenance must be [global]');
+    assert.match(hit.hits[0].name, /confidence-ladder/, 'top hit must be the seeded page');
+
+    const miss = globalAsk({ root, question: 'completely unrelated quantum chromodynamics' });
+    assert.equal(miss.hits.length, 0, 'unrelated question must return zero hits');
+  } finally {
+    rmrf(root);
+  }
+});
+
+test('global-wiki: lint flags potential-customer-leak callouts', () => {
+  const root = freshRoot('lint');
+  try {
+    globalInit({ root });
+    const answers = path.join(root, 'State', 'answers');
+    fs.writeFileSync(
+      path.join(answers, 'leaky.md'),
+      '---\nkushi_state_page: true\nscope: global\n---\n\n# Leaky\n\n> [!warning] potential-customer-leak\n> Needs follow-up.\n',
+    );
+
+    const r = globalLint({ root });
+    assert.equal(r.initialized, true);
+    const leaks = r.findings.filter((f) => f.class === 'potential-customer-leak');
+    assert.ok(leaks.length >= 1, 'lint must surface potential-customer-leak callout');
+    assert.match(leaks[0].file, /leaky\.md$/, 'finding must point at the leaky file');
+  } finally {
+    rmrf(root);
+  }
+});