neurain 0.1.0-alpha.0

package/src/core/vault_state.mjs

@@ -0,0 +1,115 @@
+// Read-only readers and helpers for the vault state formats the view tools
+// consume (session-state.json, wrap-journal.jsonl, area briefs, handoffs). Every
+// reader degrades gracefully: a missing file yields an empty result and never
+// throws, so a generic vault with no sessions still works. These readers NEVER
+// write; the one residual write in the legacy tools (the digest ack pointer)
+// stays vault-side until the session-state writes move wholesale (W-D).
+import fs from 'node:fs';
+import path from 'node:path';
+import { readText } from './fs.mjs';
+
+export function readJsonSafe(absPath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+// Parse a .jsonl file into rows, skipping blank and torn lines (a single bad
+// line never discards the whole file).
+export function readJsonl(absPath) {
+  let text;
+  try {
+    text = fs.readFileSync(absPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const rows = [];
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      rows.push(JSON.parse(trimmed));
+    } catch {
+      /* skip torn line */
+    }
+  }
+  return rows;
+}
+
+// Load session-state. Mirrors the vault reader: a missing file is an empty
+// state, but a CORRUPT file fails closed (never silently reset a registry the
+// caller might overwrite). The view tools only read, so this just surfaces the
+// corruption instead of pretending there are no sessions.
+export function loadSessionState(root, vaultCfg) {
+  const abs = path.join(root, vaultCfg.session_state);
+  if (!fs.existsSync(abs)) return { version: 1, sessions: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch (error) {
+    throw new Error(`session-state is corrupt and was not read: ${error.message}`);
+  }
+  return { version: parsed.version || 1, updated_at: parsed.updated_at || '', sessions: parsed.sessions || {} };
+}
+
+// Area-relative path -> area brief markdown path, mirroring the vault convention
+// (10_areas/<area>/current/<area-without-underscore>-area-brief.md).
+export function areaBriefPath(vaultCfg, area) {
+  const slug = String(area || '').trim();
+  if (!slug) return '';
+  const fileSlug = slug.replace(/^_+/, '') || slug;
+  return `${vaultCfg.areas_dir}/${slug}/current/${fileSlug}-area-brief.md`;
+}
+
+// Extract a "## Heading" section body from markdown (used for Current Focus,
+// Latest Cross-Session Notes, etc.).
+export function extractMarkdownSection(text, heading) {
+  const source = String(text || '');
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = source.match(new RegExp(`(?:^|\\n)## ${escaped}\\n\\n([\\s\\S]*?)(?=\\n## |$)`));
+  return match ? match[1].trim() : '';
+}
+
+export function frontmatterField(text, field) {
+  const match = String(text || '').match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return '';
+  const fm = match[1].match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
+  return fm ? fm[1].trim() : '';
+}
+
+// Pending writeback-queue rows for a session (flat root queue). Read-only.
+export function pendingQueueRows(root, vaultCfg, { sessionId = '' } = {}) {
+  const rows = readJsonl(path.join(root, vaultCfg.writeback_queue));
+  return rows.filter((row) => row && row.status === 'pending' && (!sessionId || row.session_id === sessionId));
+}
+
+// Count of pending flat-root-queue rows for one session. Mirrors the vault
+// pendingQueueCountForSession exactly. Read-only; capture/complete read this
+// AFTER their own queue write to fill the (advisory) session_state_delta.
+export function pendingCountForSession(root, vaultCfg, sessionId) {
+  if (!sessionId) return 0;
+  return readJsonl(path.join(root, vaultCfg.writeback_queue))
+    .filter((row) => row && row.session_id === sessionId && row.status === 'pending').length;
+}
+
+// Freshness of a session relative to a stale threshold (days). `now` is
+// injectable for deterministic tests.
+export function freshnessFor(lastPulse, staleDays, now = Date.now()) {
+  if (!lastPulse) return { freshness_status: 'missing_pulse', freshness_days: null, freshness_message: 'No pulse recorded yet.' };
+  const parsed = new Date(lastPulse);
+  if (Number.isNaN(parsed.getTime())) {
+    return { freshness_status: 'invalid_pulse', freshness_days: null, freshness_message: `Last pulse timestamp is invalid: ${lastPulse}` };
+  }
+  const ageDays = Math.max(0, (now - parsed.getTime()) / 86400000);
+  const rounded = Math.round(ageDays * 10) / 10;
+  if (ageDays > staleDays) {
+    return { freshness_status: 'stale', freshness_days: rounded, freshness_message: `Last pulse is ${rounded} days old. Target is ${staleDays} days or fewer.` };
+  }
+  return { freshness_status: 'fresh', freshness_days: rounded, freshness_message: `Last pulse is ${rounded} days old.` };
+}
+
+export function readTextAt(root, rel) {
+  return rel ? readText(path.join(root, rel), '') : '';
+}

package/src/core/watch.mjs

@@ -0,0 +1,282 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, isTextFile, relPath, safeResolve, walkFiles } from './fs.mjs';
+import { listJournalEvents, verifyJournal } from './journal.mjs';
+import { lessonCandidates } from './lessons.mjs';
+import { buildRecap } from './recap.mjs';
+import { inferSensitivityFromPath } from './safety.mjs';
+
+export async function watchCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  if (args.follow || args.daemon) {
+    throw new Error('Public alpha supports watch report only. Use --poll-once or omit it for a read-only snapshot.');
+  }
+  const report = buildWatchReport(root, {
+    area: args.area || '',
+    top: Number(args.top || 10),
+    sinceMinutes: Number(args['since-minutes'] || 1440),
+    includePrivate: Boolean(args['include-private']),
+    pollOnce: Boolean(args['poll-once']),
+  });
+  if (args.json) return { json: true, payload: report };
+  return {
+    text: [
+      `# Neurain watch report${report.mode === 'poll_once' ? ' [poll-once]' : ''}`,
+      '',
+      `- Root: ${root}`,
+      `- Area: ${report.area || 'all'}`,
+      '- Durable write: no',
+      `- Recent files: ${report.recent_files.length}`,
+      `- Recent events: ${report.recent_events.length}`,
+      `- Review triggers: ${report.review_triggers.length}`,
+      '',
+      '## Review triggers',
+      ...(report.review_triggers.length ? report.review_triggers.map((item) => `- [${item.priority}] ${item.reason}`) : ['- none']),
+      '',
+      '## Recent files',
+      ...(report.recent_files.length ? report.recent_files.map((item) => `- ${item.path} (${item.changed_at || 'withheld'})`) : ['- none']),
+      '',
+      '## Recent events',
+      ...(report.recent_events.length ? report.recent_events.map((item) => `- ${item.type}: ${item.summary}`) : ['- none']),
+    ].join('\n'),
+  };
+}
+
+export function buildWatchReport(root, {
+  area = '',
+  top = 10,
+  sinceMinutes = 1440,
+  includePrivate = false,
+  pollOnce = false,
+} = {}) {
+  const normalizedArea = normalizeArea(area);
+  const numericTop = Math.max(1, Math.min(Number(top || 10), 50));
+  const numericSince = Math.max(1, Math.min(Number(sinceMinutes || 1440), 60 * 24 * 30));
+  const recentFiles = recentFileSignals(root, {
+    area: normalizedArea,
+    limit: numericTop,
+    sinceMinutes: numericSince,
+    includePrivate,
+  });
+  const journalIntegrity = verifyJournal(root);
+  const recentEvents = safeRecentEvents(root, {
+    area: normalizedArea,
+    limit: numericTop,
+    includePrivate,
+  });
+  const candidates = lessonCandidates(root, { limit: Math.min(numericTop, 10), area: normalizedArea });
+  const recap = buildRecap(root, { area: normalizedArea });
+  const reviewTriggers = buildReviewTriggers({
+    journalIntegrity,
+    recentEvents,
+    recentFiles,
+    candidates,
+    recap,
+    includePrivate,
+  });
+
+  return {
+    ok: true,
+    command: 'watch',
+    mode: pollOnce ? 'poll_once' : 'snapshot',
+    root,
+    area: normalizedArea || null,
+    durable_write: false,
+    write_policy: 'read_only_candidate_report',
+    since_minutes: numericSince,
+    recent_files: recentFiles,
+    recent_events: recentEvents,
+    lesson_candidate_count: candidates.length,
+    lesson_candidate_ids: candidates.map((candidate) => candidate.id),
+    recap_signal_count: recap.recent_signals.length,
+    open_work_hint_count: recap.open_work_hints.length,
+    journal_integrity: {
+      ok: journalIntegrity.ok,
+      line_count: journalIntegrity.line_count,
+      error_count: journalIntegrity.error_count,
+    },
+    review_triggers: reviewTriggers,
+    next_step: reviewTriggers.length
+      ? 'Review the watch report. Run wrap dry-run or review worker next; do not promote lessons silently.'
+      : 'No strong watch trigger found. Continue work and run watch again after meaningful changes.',
+  };
+}
+
+function recentFileSignals(root, { area, limit, sinceMinutes, includePrivate }) {
+  const cutoff = Date.now() - sinceMinutes * 60 * 1000;
+  const files = walkFiles(root, { includeRaw: false, maxFiles: 50000 })
+    .map((abs) => fileSignal(root, abs, includePrivate))
+    .filter((item) => item)
+    .filter((item) => !area || item.area === area)
+    .filter((item) => item.mtime_ms >= cutoff)
+    .sort((a, b) => b.mtime_ms - a.mtime_ms)
+    .slice(0, limit);
+  return files.map(({ mtime_ms, ...item }) => item);
+}
+
+function fileSignal(root, abs, includePrivate) {
+  const rel = relPath(root, abs);
+  if (!isTextFile(rel)) return null;
+  if (ignoredWatchPath(rel)) return null;
+  let stat;
+  try {
+    stat = fs.statSync(abs);
+  } catch {
+    return null;
+  }
+  const sensitivity = inferSensitivityFromPath(rel);
+  const withheld = sensitivity === 'private' && !includePrivate;
+  return {
+    path: withheld ? '[private path withheld]' : rel,
+    path_withheld: withheld,
+    area: withheld ? '[withheld]' : areaFromRel(rel),
+    sensitivity,
+    changed_at: withheld ? null : new Date(stat.mtimeMs).toISOString(),
+    age_minutes: withheld ? null : Math.max(0, Math.round((Date.now() - stat.mtimeMs) / 60000)),
+    size_bytes: withheld ? null : stat.size,
+    mtime_ms: stat.mtimeMs,
+  };
+}
+
+function safeRecentEvents(root, { area, limit, includePrivate }) {
+  const events = listJournalEvents(root, { limit: Math.max(limit * 2, 20) }).events
+    .filter((event) => eventMatchesArea(event, area))
+    .slice(0, limit);
+  return events.map((event) => sanitizeEvent(event, includePrivate));
+}
+
+function sanitizeEvent(event, includePrivate) {
+  const unsafe = event.sensitivity === 'private' || event.prompt_context_allowed === false || event.safety?.cross_host_allowed === false;
+  const hide = unsafe && !includePrivate;
+  return {
+    event_id: event.event_id,
+    type: event.type,
+    created_at: event.created_at,
+    sensitivity: event.sensitivity,
+    prompt_context_allowed: Boolean(event.prompt_context_allowed) && !hide,
+    source_ids: hide ? [] : event.source_ids || [],
+    source_ids_withheld: hide,
+    summary: hide && !event.redacted ? '[event summary withheld by safety policy]' : event.summary,
+    redacted: Boolean(event.redacted) || hide,
+    safety: {
+      secret_like: event.safety?.secret_like || null,
+      injection_like: event.safety?.injection_like || null,
+      indexing_allowed: Boolean(event.safety?.indexing_allowed) && !hide,
+      cross_host_allowed: Boolean(event.safety?.cross_host_allowed) && !hide,
+    },
+  };
+}
+
+function buildReviewTriggers({ journalIntegrity, recentEvents, recentFiles, candidates, recap, includePrivate }) {
+  const triggers = [];
+  if (!journalIntegrity.ok) {
+    triggers.push({
+      id: 'journal-integrity',
+      priority: 'high',
+      reason: `journal integrity has ${journalIntegrity.error_count} error(s)`,
+      source_event_ids: [],
+      source_candidate_ids: [],
+      source_paths: [],
+      source_paths_withheld: false,
+    });
+  }
+  const reviewEvents = recentEvents.filter((event) => ['correction', 'review', 'rollback'].includes(event.type));
+  if (reviewEvents.length) {
+    triggers.push({
+      id: 'review-events',
+      priority: 'high',
+      reason: `${reviewEvents.length} correction/review/rollback event(s) need review-worker attention`,
+      source_event_ids: reviewEvents.map((event) => event.event_id),
+      source_candidate_ids: [],
+      source_paths: [],
+      source_paths_withheld: false,
+    });
+  }
+  const unsafeEvents = recentEvents.filter((event) => event.redacted || !event.safety.cross_host_allowed);
+  if (unsafeEvents.length) {
+    triggers.push({
+      id: 'unsafe-events',
+      priority: 'medium',
+      reason: `${unsafeEvents.length} unsafe or private event(s) were withheld from prompt context`,
+      source_event_ids: unsafeEvents.map((event) => event.event_id),
+      source_candidate_ids: [],
+      source_paths: [],
+      source_paths_withheld: false,
+    });
+  }
+  if (candidates.length) {
+    const candidateSources = sanitizeTriggerPaths(candidates.flatMap((candidate) => candidate.source_ids || []), includePrivate);
+    triggers.push({
+      id: 'lesson-candidates',
+      priority: 'medium',
+      reason: `${candidates.length} lesson candidate(s) are available for manual review`,
+      source_event_ids: [],
+      source_candidate_ids: candidates.map((candidate) => candidate.id),
+      source_paths: candidateSources.paths,
+      source_paths_withheld: candidateSources.withheld,
+    });
+  }
+  if (recap.open_work_hints.length) {
+    const recapSources = sanitizeTriggerPaths(recap.sources_checked || [], includePrivate);
+    triggers.push({
+      id: 'open-work',
+      priority: 'medium',
+      reason: `${recap.open_work_hints.length} open work hint(s) found in recap sources`,
+      source_event_ids: [],
+      source_candidate_ids: [],
+      source_paths: recapSources.paths,
+      source_paths_withheld: recapSources.withheld,
+    });
+  }
+  if (recentFiles.length) {
+    triggers.push({
+      id: 'recent-files',
+      priority: 'low',
+      reason: `${recentFiles.length} recently changed text file(s) observed`,
+      source_event_ids: [],
+      source_candidate_ids: [],
+      source_paths: recentFiles.map((item) => item.path),
+      source_paths_withheld: recentFiles.some((item) => item.path_withheld),
+    });
+  }
+  return triggers;
+}
+
+function sanitizeTriggerPaths(paths, includePrivate) {
+  let withheld = false;
+  const safePaths = [];
+  for (const rel of paths) {
+    if (inferSensitivityFromPath(rel) === 'private' && !includePrivate) {
+      withheld = true;
+      continue;
+    }
+    safePaths.push(rel);
+  }
+  return { paths: safePaths, withheld };
+}
+
+function ignoredWatchPath(rel) {
+  return [
+    /^output\/receipts\//,
+    /^output\/benchmarks\//,
+    /^output\/reviews\//,
+    /^00_system\/neurain\/events\.ndjson$/,
+    /^00_system\/sessions\/session-state\.json$/,
+  ].some((pattern) => pattern.test(rel));
+}
+
+function eventMatchesArea(event, area) {
+  if (!area) return true;
+  const areaPrefix = `10_areas/_${area}/`;
+  return (event.source_ids || []).some((source) => String(source).startsWith(areaPrefix))
+    || String(event.scope || '').replace(/^_/, '') === area;
+}
+
+function areaFromRel(rel) {
+  const match = String(rel).match(/^10_areas\/_?([^/]+)\//);
+  return match ? match[1] : null;
+}
+
+function normalizeArea(area) {
+  return String(area || '').replace(/^_/, '').trim();
+}

package/src/core/wiki_log.mjs

@@ -0,0 +1,29 @@
+// Append-only wiki operations log (W-B). capture/complete record one operational
+// line each (source id, paths, areas, status) here. This is an operational
+// receipt, NOT session working memory or canonical knowledge, so the engine owns
+// the append directly; the vault shuttle must NOT also append a duplicate line
+// (single-owner rule from the B4 cross-review). Faithful port of the vault
+// appendWikiLog.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, readText, timestamp } from './fs.mjs';
+
+export function appendWikiLog(root, vaultCfg, kind, title, lines = []) {
+  const day = timestamp().slice(0, 10);
+  const logAbs = path.join(root, vaultCfg.wiki_dir, 'log.md');
+  ensureDir(path.dirname(logAbs));
+  if (!fs.existsSync(logAbs)) {
+    fs.writeFileSync(
+      logAbs,
+      `---\ntitle: Wiki Log\ntype: log\nareas: []\nsources: []\nstatus: active\nsensitivity: internal\nupdated: ${day}\n---\n\n# Wiki Log\n\nAppend-only operation log for root wiki maintenance.\n`,
+    );
+  }
+  const body = lines.length ? `\n${lines.map((line) => `- ${line}`).join('\n')}\n` : '';
+  fs.appendFileSync(logAbs, `\n## [${day}] ${kind} | ${title}\n${body}`);
+  return path.relative(root, logAbs).split(path.sep).join('/');
+}
+
+// best-effort: callers that prefer readText for existence can reuse this
+export function wikiLogExists(root, vaultCfg) {
+  return Boolean(readText(path.join(root, vaultCfg.wiki_dir, 'log.md'), ''));
+}

package/src/core/wrap.mjs

@@ -0,0 +1,62 @@
+import { listCapabilities } from './capabilities.mjs';
+import { doctorCommand } from './doctor.mjs';
+import { lessonCandidates, listLessons } from './lessons.mjs';
+import { buildRecap } from './recap.mjs';
+import { absPath } from './fs.mjs';
+
+export async function wrapCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const area = args.area || '';
+  const dryRun = args.apply ? false : true;
+  if (!dryRun) {
+    throw new Error('Public alpha supports wrap dry-run only. Durable lesson promotion is intentionally unavailable.');
+  }
+  const doctor = await doctorCommand({ _: [root], json: true });
+  const lessons = listLessons(root, { area });
+  const candidates = lessonCandidates(root, { limit: Number(args.top || 5), area });
+  const recap = buildRecap(root, { area });
+  const capabilities = listCapabilities({ query: 'wrap lesson recap rollback capability', limit: 5 });
+  const payload = {
+    ok: true,
+    command: 'wrap',
+    root,
+    dry_run: true,
+    durable_write: false,
+    doctor: doctor.payload,
+    lesson_state: {
+      active_lessons: lessons.length,
+      candidate_count: candidates.length,
+      promotion_available: candidates.some((candidate) => candidate.safety?.promotion_allowed),
+      promotion_note: candidates.some((candidate) => candidate.safety?.promotion_allowed)
+        ? 'Promote one reviewed candidate with `neurain lessons promote <folder> --candidate-id <id> --confirm "1건 저장 진행"`.'
+        : 'No safe promotable candidate in this preview.',
+    },
+    recap,
+    candidates,
+    capabilities,
+    next_step: candidates.length
+      ? 'Review lesson candidates. Do not promote until rollback proof exists.'
+      : 'No strong lesson candidates. Continue work and run wrap again after meaningful changes.',
+  };
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      '# Neurain wrap dry-run',
+      '',
+      `- Root: ${root}`,
+      `- Doctor OK: ${doctor.payload.ok ? 'yes' : 'no'}`,
+      `- Active lessons: ${lessons.length}`,
+      `- Lesson candidates: ${candidates.length}`,
+      '- Durable write: no',
+      '',
+      '## Recap signals',
+      ...(recap.recent_signals.length ? recap.recent_signals.map((line) => `- ${line}`) : ['- none']),
+      '',
+      '## Candidate preview',
+      ...(candidates.length ? candidates.map((candidate) => `- ${candidate.id}: ${candidate.title} (${candidate.source_ids.join(', ')})`) : ['- none']),
+      '',
+      '## Useful capabilities',
+      ...capabilities.map((capability) => `- ${capability.id}: ${capability.commands[0]}`),
+    ].join('\n'),
+  };
+}