neurain 0.1.0-alpha.0

package/src/core/curator.mjs

@@ -0,0 +1,351 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, compactStamp, ensureDir, safeResolve, sha256, timestamp } from './fs.mjs';
+
+const registryRel = '00_system/neurain/lessons.md';
+const confirmPhrase = '1건 저장 진행';
+
+export async function curatorCommand(args) {
+  const [subcommand, ...rest] = args._;
+  const root = absPath(rest[0] || args.root || process.cwd());
+  if (!subcommand || subcommand === 'status') return renderCuratorStatus(root, args);
+  if (subcommand === 'run') return renderCuratorRun(root, args);
+  if (subcommand === 'rollback') return renderCuratorRollback(root, args);
+  throw new Error(`Unknown curator command: ${subcommand}. Use "curator status", "curator run", or "curator rollback".`);
+}
+
+export function curatorStatus(root, {
+  staleDays = 30,
+  archiveDays = 90,
+} = {}) {
+  const registryAbs = safeResolve(root, registryRel);
+  const registryText = fs.existsSync(registryAbs) ? fs.readFileSync(registryAbs, 'utf8') : '';
+  const plan = curatorPlan(registryText, {
+    staleDays: Number(staleDays || 30),
+    archiveDays: Number(archiveDays || 90),
+  });
+  return {
+    ok: true,
+    command: 'curator status',
+    root,
+    durable_write: false,
+    registry_path: registryRel,
+    policy: curatorPolicy(staleDays, archiveDays),
+    counts: plan.counts,
+    planned_changes: plan.planned_changes,
+    protected_items: plan.protected_items,
+    next_step: plan.planned_changes.length
+      ? 'Run curator run --dry-run first, then apply only with the exact confirmation phrase.'
+      : 'No curator lifecycle changes are currently recommended.',
+  };
+}
+
+export function runCurator(root, {
+  confirm = '',
+  dryRun = false,
+  staleDays = 30,
+  archiveDays = 90,
+} = {}) {
+  if (!dryRun && String(confirm || '') !== confirmPhrase) {
+    throw new Error(`Curator run requires --dry-run or --confirm "${confirmPhrase}".`);
+  }
+  const registryAbs = safeResolve(root, registryRel);
+  const beforeText = fs.existsSync(registryAbs) ? fs.readFileSync(registryAbs, 'utf8') : '';
+  const plan = curatorPlan(beforeText, {
+    staleDays: Number(staleDays || 30),
+    archiveDays: Number(archiveDays || 90),
+  });
+  const afterText = applyCuratorPlan(beforeText, plan.planned_changes);
+  const changed = beforeText !== afterText;
+  const stamp = compactStamp();
+  const receiptRel = changed
+    ? `output/receipts/curator/${stamp}-${sha256(`${beforeText}:${afterText}`).slice(0, 12)}-curator-run.json`
+    : null;
+  const result = {
+    ok: true,
+    command: 'curator run',
+    generated_at: timestamp(),
+    dry_run: Boolean(dryRun),
+    applied: Boolean(!dryRun && changed),
+    durable_write: Boolean(!dryRun && changed),
+    registry_path: registryRel,
+    receipt_path: !dryRun && changed ? receiptRel : null,
+    policy: curatorPolicy(staleDays, archiveDays),
+    counts: plan.counts,
+    planned_changes: plan.planned_changes,
+    protected_items: plan.protected_items,
+    snapshot: {
+      before_sha256: sha256(beforeText),
+      after_sha256: sha256(afterText),
+      before_text: dryRun ? null : beforeText,
+    },
+    receipt_status: dryRun || !changed ? 'not_written' : 'pending_registry_write',
+    write_policy: 'snapshot_then_lifecycle_status_update_only',
+    no_delete: true,
+  };
+  if (!dryRun && changed) {
+    ensureDir(path.dirname(registryAbs));
+    ensureDir(path.dirname(safeResolve(root, receiptRel)));
+    const receiptAbs = safeResolve(root, receiptRel);
+    fs.writeFileSync(receiptAbs, `${JSON.stringify(result, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    atomicWriteFile(registryAbs, afterText);
+    result.applied = true;
+    result.durable_write = true;
+    result.receipt_status = 'observed_after_registry_write';
+    fs.writeFileSync(receiptAbs, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  }
+  return result;
+}
+
+export function rollbackCurator(root, { receiptPath } = {}) {
+  if (!receiptPath) throw new Error('Curator rollback requires --receipt <path>.');
+  const receiptAbs = safeResolve(root, receiptPath);
+  if (!fs.existsSync(receiptAbs)) throw new Error(`Receipt does not exist: ${receiptPath}`);
+  const receipt = JSON.parse(fs.readFileSync(receiptAbs, 'utf8'));
+  if (receipt.command !== 'curator run') throw new Error(`Not a curator run receipt: ${receiptPath}`);
+  const registryAbs = safeResolve(root, receipt.registry_path || registryRel);
+  const beforeText = receipt.snapshot?.before_text;
+  if (typeof beforeText !== 'string') throw new Error('Curator receipt is missing snapshot.before_text.');
+  const currentText = fs.existsSync(registryAbs) ? fs.readFileSync(registryAbs, 'utf8') : '';
+  const currentHash = sha256(currentText);
+  const beforeHash = receipt.snapshot.before_sha256;
+  const afterHash = receipt.snapshot.after_sha256;
+  const stamp = compactStamp();
+  const rollbackRel = `output/receipts/curator/${stamp}-${sha256(receiptPath).slice(0, 12)}-curator-rollback.json`;
+  const result = {
+    ok: false,
+    command: 'curator rollback',
+    generated_at: timestamp(),
+    source_receipt_path: receiptPath,
+    registry_path: receipt.registry_path || registryRel,
+    restored: false,
+    idempotent: false,
+    reason: '',
+  };
+  if (currentHash === beforeHash) {
+    result.ok = true;
+    result.idempotent = true;
+    result.reason = 'registry already matches snapshot before state';
+  } else if (currentHash !== afterHash) {
+    result.reason = 'registry changed since curator run; refusing rollback';
+  } else {
+    atomicWriteFile(registryAbs, beforeText);
+    result.ok = true;
+    result.restored = true;
+    result.before_sha256 = currentHash;
+    result.after_sha256 = beforeHash;
+  }
+  ensureDir(path.dirname(safeResolve(root, rollbackRel)));
+  fs.writeFileSync(safeResolve(root, rollbackRel), `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  return { ...result, receipt_path: rollbackRel };
+}
+
+function renderCuratorStatus(root, args) {
+  const payload = curatorStatus(root, {
+    staleDays: args['stale-days'] || 30,
+    archiveDays: args['archive-days'] || 90,
+  });
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      '# Neurain curator status',
+      '',
+      `- Root: ${root}`,
+      '- Durable write: no',
+      `- Planned changes: ${payload.planned_changes.length}`,
+      `- Protected items: ${payload.protected_items.length}`,
+    ].join('\n'),
+  };
+}
+
+function renderCuratorRun(root, args) {
+  const payload = runCurator(root, {
+    confirm: args.confirm,
+    dryRun: Boolean(args['dry-run']),
+    staleDays: args['stale-days'] || 30,
+    archiveDays: args['archive-days'] || 90,
+  });
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      `# Neurain curator run${payload.dry_run ? ' [dry-run]' : ''}`,
+      '',
+      `- Root: ${root}`,
+      `- Applied: ${payload.applied ? 'yes' : 'no'}`,
+      `- Planned changes: ${payload.planned_changes.length}`,
+      `- Protected items: ${payload.protected_items.length}`,
+      payload.receipt_path ? `- Receipt: ${payload.receipt_path}` : '',
+    ].filter(Boolean).join('\n'),
+  };
+}
+
+function renderCuratorRollback(root, args) {
+  const payload = rollbackCurator(root, { receiptPath: args.receipt || args._[1] || args.path });
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      '# Neurain curator rollback',
+      '',
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Restored: ${payload.restored ? 'yes' : 'no'}`,
+      payload.reason ? `- Reason: ${payload.reason}` : '',
+      payload.receipt_path ? `- Receipt: ${payload.receipt_path}` : '',
+    ].filter(Boolean).join('\n'),
+  };
+}
+
+function curatorPolicy(staleDays, archiveDays) {
+  return {
+    stale_after_days: Number(staleDays || 30),
+    archive_after_days: Number(archiveDays || 90),
+    mutates: ['Status field only'],
+    never_deletes: true,
+    protects: ['pinned lessons', 'human-authored lessons', 'private lessons', 'non-agent-created lessons'],
+  };
+}
+
+function curatorPlan(registryText, { staleDays, archiveDays }) {
+  const lessons = registryLessons(registryText);
+  const planned = [];
+  const protectedItems = [];
+  const counts = { active: 0, stale: 0, archived: 0, protected: 0, agent_created: 0 };
+  for (const lesson of lessons) {
+    if (lesson.status === 'active') counts.active += 1;
+    if (lesson.status === 'stale') counts.stale += 1;
+    if (lesson.status === 'archived') counts.archived += 1;
+    if (lesson.agent_created) counts.agent_created += 1;
+    const protectedReason = protectedReasonFor(lesson);
+    if (protectedReason) {
+      counts.protected += 1;
+      protectedItems.push(publicLessonItem(lesson, protectedReason));
+      continue;
+    }
+    const age = ageDays(lesson.last_used || lesson.last_verified);
+    if (age == null) continue;
+    if (lesson.status === 'active' && age >= staleDays) {
+      planned.push(changeFor(lesson, 'stale', age, `last use is ${age} day(s) old`));
+    } else if (lesson.status === 'stale' && age >= archiveDays) {
+      planned.push(changeFor(lesson, 'archived', age, `stale lesson last use is ${age} day(s) old`));
+    }
+  }
+  return { lessons, planned_changes: planned, protected_items: protectedItems, counts };
+}
+
+function registryLessons(text) {
+  const chunks = String(text || '').split(/(?=\n##\s+)/g);
+  return chunks.map((block, index) => parseRegistryBlock(block, index)).filter(Boolean);
+}
+
+function parseRegistryBlock(block, index = 0) {
+  const heading = block.match(/^\n?##\s+(.+)$/m)?.[1]?.trim();
+  if (!heading || /Rules|Registration Criteria|Template|Active Lessons/i.test(heading)) return null;
+  if (/No durable lessons recorded yet/i.test(block)) return null;
+  const rawStatus = field(block, 'Status') || 'active';
+  const status = normalizeStatus(rawStatus);
+  const candidateHash = field(block, 'Candidate hash');
+  const reviewReceipt = field(block, 'Review receipt');
+  const author = field(block, 'Author') || field(block, 'Created by');
+  const sensitivity = normalizeSensitivity(field(block, 'Sensitivity') || 'internal');
+  return {
+    id: `lesson-${sha256(`${index}:${heading}:${candidateHash}:${reviewReceipt}`).slice(0, 12)}`,
+    title: heading,
+    block,
+    status,
+    sensitivity,
+    scope: field(block, 'Scope') || 'global',
+    pinned: truthy(field(block, 'Pinned')) || /^pinned$/i.test(rawStatus),
+    human_authored: truthy(field(block, 'Human authored')) || /human|user|manual/i.test(author),
+    agent_created: Boolean(candidateHash || reviewReceipt || /neurain|agent|cli/i.test(author)),
+    last_used: field(block, 'Last used'),
+    last_verified: field(block, 'Last verified'),
+    candidate_hash: candidateHash || null,
+    review_receipt: reviewReceipt || null,
+  };
+}
+
+function publicLessonItem(lesson, reason) {
+  const privateItem = lesson.sensitivity === 'private';
+  return {
+    lesson_id: lesson.id,
+    title: privateItem ? '[private title withheld]' : lesson.title,
+    status: lesson.status,
+    sensitivity: lesson.sensitivity,
+    scope: privateItem ? '[withheld]' : lesson.scope,
+    reason,
+  };
+}
+
+function changeFor(lesson, toStatus, age, reason) {
+  return {
+    lesson_id: lesson.id,
+    title: lesson.title,
+    from_status: lesson.status,
+    to_status: toStatus,
+    age_days: age,
+    reason,
+    source: lesson.review_receipt || lesson.candidate_hash || null,
+  };
+}
+
+function applyCuratorPlan(text, changes) {
+  if (!changes.length) return text;
+  const changeById = new Map(changes.map((change) => [change.lesson_id, change]));
+  return String(text || '').split(/(?=\n##\s+)/g).map((block, index) => {
+    const lesson = parseRegistryBlock(block, index);
+    if (!lesson) return block;
+    const change = changeById.get(lesson.id);
+    if (!change) return block;
+    return updateStatusLine(block, change.to_status);
+  }).join('');
+}
+
+function updateStatusLine(block, status) {
+  if (/^- Status:\s*.+$/im.test(block)) return block.replace(/^- Status:\s*.+$/im, `- Status: ${status}`);
+  return block.replace(/(\n\s*)$/, `\n- Status: ${status}$1`);
+}
+
+function protectedReasonFor(lesson) {
+  if (lesson.pinned) return 'pinned lesson is protected';
+  if (lesson.human_authored) return 'human-authored lesson is protected';
+  if (lesson.sensitivity === 'private') return 'private lesson is protected';
+  if (!lesson.agent_created) return 'non-agent-created lesson is protected';
+  return '';
+}
+
+function normalizeStatus(value) {
+  const status = String(value || 'active').trim().toLowerCase();
+  if (status === 'archive') return 'archived';
+  if (['active', 'stale', 'archived', 'obsolete'].includes(status)) return status;
+  return 'active';
+}
+
+function normalizeSensitivity(value) {
+  const sensitivity = String(value || 'internal').trim().toLowerCase();
+  if (sensitivity.includes('private')) return 'private';
+  if (sensitivity.includes('public')) return 'public';
+  if (sensitivity.includes('mixed')) return 'mixed';
+  return 'internal';
+}
+
+function truthy(value) {
+  return /^(true|yes|1|pinned)$/i.test(String(value || '').trim());
+}
+
+function ageDays(value) {
+  const match = String(value || '').match(/\d{4}-\d{2}-\d{2}/);
+  if (!match) return null;
+  const at = Date.parse(`${match[0]}T00:00:00Z`);
+  if (!Number.isFinite(at)) return null;
+  return Math.max(0, Math.floor((Date.now() - at) / 86400000));
+}
+
+function atomicWriteFile(file, content) {
+  ensureDir(path.dirname(file));
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, content, { encoding: 'utf8', flag: 'wx' });
+  fs.renameSync(tmp, file);
+}
+
+function field(text, name) {
+  return text.match(new RegExp(`^-\\s*${name}:\\s*(.+)$`, 'im'))?.[1]?.trim() || '';
+}