neurain 0.1.0-alpha.0

package/src/core/init.mjs

@@ -0,0 +1,194 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, safeResolve, writeFileNoOverwrite } from './fs.mjs';
+
+const dirs = [
+  '00_system/neurain',
+  '00_system/sessions/handoffs',
+  '10_areas',
+  '20_hubs',
+  '90_archive',
+  'raw/_inbox',
+  'wiki',
+  'output',
+  'output/receipts/events',
+  'output/receipts/recall',
+];
+
+export async function initCommand(args) {
+  const root = absPath(args._[0]);
+  const dryRun = Boolean(args['dry-run']);
+  const lang = args.lang === 'en' ? 'en' : 'ko';
+  const area = String(args.area || 'general').replace(/^_+/, '') || 'general';
+  const created = [];
+  const skipped = [];
+
+  for (const rel of dirs) {
+    const dir = safeResolve(root, rel);
+    if (fs.existsSync(dir)) skipped.push(`${rel}/`);
+    else {
+      if (!dryRun) fs.mkdirSync(dir, { recursive: true });
+      created.push(`${rel}/`);
+    }
+  }
+
+  const files = starterFiles(area, lang);
+  for (const [rel, content] of Object.entries(files)) {
+    writeFileNoOverwrite(safeResolve(root, rel), content, { dryRun, created, skipped });
+  }
+
+  const summary = {
+    ok: true,
+    command: 'init',
+    root,
+    dry_run: dryRun,
+    created: created.map((file) => path.relative(root, file).split(path.sep).join('/')).map((v) => v || '.'),
+    skipped: skipped.map((file) => (path.isAbsolute(file) ? path.relative(root, file).split(path.sep).join('/') : file)),
+    next_steps: [
+      `Run: neurain doctor "${root}"`,
+      `Run: neurain connect codex "${root}" --dry-run`,
+      `Ask your agent to use Neurain status before work and Neurain capture after important work.`,
+    ],
+  };
+
+  if (args.json) return { json: true, payload: summary };
+  return {
+    text: [
+      `# Neurain init${dryRun ? ' [dry-run]' : ''}`,
+      '',
+      `- Root: ${root}`,
+      `- Created: ${summary.created.length}`,
+      `- Skipped existing: ${summary.skipped.length}`,
+      '',
+      'Next:',
+      ...summary.next_steps.map((step) => `- ${step}`),
+    ].join('\n'),
+  };
+}
+
+export function starterFiles(area, lang = 'ko') {
+  const areaRoot = `10_areas/${area}`;
+  const areaTitle = area.replace(/[-_]+/g, ' ');
+  return {
+    'neurain.config.json': `${JSON.stringify({
+      version: 1,
+      language_default: lang,
+      areas_dir: '10_areas',
+      wiki_dir: 'wiki',
+      raw_dir: 'raw',
+      output_dir: 'output',
+      created_by: 'neurain-cli',
+    }, null, 2)}\n`,
+    'AGENTS.md': lang === 'en' ? agentsEn() : agentsKo(),
+    'CLAUDE.md': lang === 'en' ? agentsEn('CLAUDE') : agentsKo('CLAUDE'),
+    'README.md': readme(lang),
+    'index.md': `# Neurain Vault\n\n## Areas\n\n- [${areaTitle}](${areaRoot}/index.md)\n`,
+    'log.md': '# Vault Log\n\n',
+    '00_system/neurain-startup.md': startup(lang),
+    '00_system/neurain/neurain-rules.md': rules(lang),
+    '00_system/neurain/lessons.md': lessons(lang),
+    '00_system/neurain/events.ndjson': '',
+    '00_system/neurain/search-index-registry.json': '{\n  "areas": {}\n}\n',
+    '00_system/neurain/memory-write-registry.json': '{\n  "version": 1,\n  "areas": {}\n}\n',
+    '00_system/sessions/session-state.json': '{\n  "version": 1,\n  "sessions": {}\n}\n',
+    '00_system/sessions/session-registry.md': '# Session Registry\n\n',
+    '00_system/sessions/handoffs/.gitkeep': '',
+    'wiki/index.md': '# Wiki Index\n\n',
+    'wiki/log.md': '# Wiki Log\n\n',
+    [`${areaRoot}/_area.md`]: `# ${areaTitle}\n\n- purpose: describe this work area\n- sensitivity: internal\n- source status: native\n`,
+    [`${areaRoot}/index.md`]: `# ${areaTitle} Index\n\nAdd key documents here.\n`,
+    [`${areaRoot}/log.md`]: `# ${areaTitle} Log\n\n`,
+    [`${areaRoot}/sources_map.md`]: `# ${areaTitle} Sources Map\n\nMap source files to Neurain layers here.\n`,
+    [`${areaRoot}/current/${area}-area-brief.md`]: `# ${areaTitle} Area Brief\n\nCurrent working context will appear here.\n`,
+  };
+}
+
+function readme(lang) {
+  if (lang === 'en') {
+    return '# Neurain Vault\n\nThis folder is a local-first AI Knowledge OS vault. Your files stay local unless your AI host reads them with your approval.\n\nStart with `neurain doctor .`.\n';
+  }
+  return '# Neurain Vault\n\n이 폴더는 local-first AI Knowledge OS vault입니다. 사용자의 파일은 사용자가 연결한 AI host가 읽기 전까지 로컬에 남습니다.\n\n먼저 `neurain doctor .`를 실행하세요.\n';
+}
+
+function startup(lang) {
+  return lang === 'en'
+    ? '# Neurain Startup\n\nRead this before using Neurain. Check status, search source-grounded knowledge, capture important work, and run wrap dry-run after meaningful work so future sessions can learn from lesson candidates.\n'
+    : '# Neurain Startup\n\nNeurain을 쓰기 전에 이 문서를 읽으세요. 상태를 확인하고, 근거 기반으로 검색하고, 중요한 작업을 캡처합니다. 의미 있는 작업 후에는 wrap dry-run을 실행해 다음 세션이 lesson 후보를 보고 더 잘 이어받게 합니다.\n';
+}
+
+function rules(lang) {
+  return lang === 'en'
+    ? '# Neurain Rules\n\n- Preserve source evidence before durable interpretation.\n- Ask before risky writes.\n- Keep private material local.\n- Lessons are previewed before promotion. Public alpha does not silently promote lessons.\n'
+    : '# Neurain Rules\n\n- 오래 남길 해석 전에 원본 근거를 보존합니다.\n- 위험한 쓰기는 먼저 확인합니다.\n- private 자료는 로컬에 둡니다.\n- lesson은 승격 전에 먼저 미리보기로 확인합니다. public alpha는 lesson을 조용히 승격하지 않습니다.\n';
+}
+
+function lessons(lang) {
+  if (lang === 'en') {
+    return `# Neurain Lessons
+
+Durable lessons for recurring agent mistakes and corrections.
+
+## Rules
+
+- Add a lesson only when a mistake or correction is likely to recur.
+- Keep each lesson short and source-grounded.
+- Include trigger, correction, scope, status, and sensitivity.
+- Do not store private source details here.
+- Public alpha can list and preview lesson candidates, but cannot silently promote lessons.
+
+## Template
+
+\`\`\`markdown
+## YYYY-MM-DD | short lesson title
+
+- Trigger:
+- Correction:
+- Scope: global | area | session
+- Status: active | stale | archived | obsolete
+- Pinned: true | false
+- Sensitivity: internal
+\`\`\`
+
+## Active Lessons
+
+No durable lessons recorded yet.
+`;
+  }
+  return `# Neurain Lessons
+
+반복되는 agent 실수와 correction을 위한 durable lesson registry입니다.
+
+## Rules
+
+- 반복될 가능성이 큰 실수나 correction만 lesson으로 남깁니다.
+- 각 lesson은 짧고 source-grounded해야 합니다.
+- trigger, correction, scope, status, sensitivity를 포함합니다.
+- private source details는 여기에 저장하지 않습니다.
+- public alpha는 lesson list와 candidate preview만 제공하며, lesson을 조용히 승격하지 않습니다.
+
+## Template
+
+\`\`\`markdown
+## YYYY-MM-DD | short lesson title
+
+- Trigger:
+- Correction:
+- Scope: global | area | session
+- Status: active | stale | archived | obsolete
+- Pinned: true | false
+- Sensitivity: internal
+\`\`\`
+
+## Active Lessons
+
+No durable lessons recorded yet.
+`;
+}
+
+function agentsEn(name = 'AGENTS') {
+  return `# ${name}.md\n\nNeurain is local-first. Use the local CLI or MCP server to inspect status, search, and capture. Do not expose private files unless the user asks.\n`;
+}
+
+function agentsKo(name = 'AGENTS') {
+  return `# ${name}.md\n\nNeurain은 local-first입니다. 로컬 CLI 또는 MCP server로 상태 확인, 검색, 캡처를 수행합니다. 사용자가 요청하지 않은 private 파일은 노출하지 않습니다.\n`;
+}

package/src/core/journal.mjs

@@ -0,0 +1,269 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, compactStamp, ensureDir, readText, safeResolve, sha256, timestamp } from './fs.mjs';
+import { inferSensitivityFromPath, maxSensitivity, redactedPreview } from './safety.mjs';
+
+export const journalRel = '00_system/neurain/events.ndjson';
+const receiptDirRel = 'output/receipts/events';
+const allowedTypes = new Set([
+  'wrap',
+  'review',
+  'test',
+  'correction',
+  'adoption',
+  'rollback',
+  'sync',
+  'lesson',
+  'recall',
+  'curator',
+  'watch',
+  'lifecycle',
+  'note',
+]);
+
+export async function journalCommand(args) {
+  const [subcommand, ...rest] = args._;
+  const root = absPath(rest[0] || args.root || process.cwd());
+  if (!subcommand || subcommand === 'list') return renderJournalList(root, args);
+  if (subcommand === 'add') return renderJournalAdd(root, args);
+  if (subcommand === 'verify') return renderJournalVerify(root, args);
+  throw new Error(`Unknown journal command: ${subcommand}. Use "journal list", "journal add", or "journal verify".`);
+}
+
+export function appendJournalEvent(root, {
+  type = 'note',
+  summary = '',
+  source = '',
+  host = '',
+  scope = 'global',
+  confirm = '',
+  dryRun = false,
+  metadata = null,
+} = {}) {
+  const normalizedType = normalizeType(type);
+  const rawSummary = String(summary || '');
+  if (!rawSummary.trim()) throw new Error('Journal event requires --summary <text>.');
+  if (rawSummary.length > 20000) throw new Error('Journal summary is too large. Keep it under 20000 characters.');
+  if (!dryRun && String(confirm || '') !== '1건 저장 진행') {
+    throw new Error('Journal add requires --confirm "1건 저장 진행".');
+  }
+  const sourceIds = normalizeSourceIds(source);
+  const preview = redactedPreview(rawSummary, 500);
+  const sensitivity = maxSensitivity([
+    ...sourceIds.map((item) => inferSensitivityFromPath(item)),
+    preview.secret_like ? 'private' : 'internal',
+    String(scope || '').includes('private') ? 'private' : 'internal',
+  ]);
+  const eventId = `event-${crypto.randomUUID()}`;
+  const receiptRel = `${receiptDirRel}/${compactStamp()}-${normalizedType}-${eventId.slice(-12)}.json`;
+  const event = {
+    version: 1,
+    event_id: eventId,
+    type: normalizedType,
+    created_at: timestamp(),
+    scope: String(scope || 'global'),
+    host: String(host || 'cli'),
+    source_ids: sourceIds,
+    receipt_path: receiptRel,
+    sensitivity,
+    prompt_context_allowed: !preview.secret_like && !preview.injection_like && sensitivity !== 'private',
+    summary: preview.text,
+    redacted: preview.redacted,
+    safety: {
+      secret_like: preview.secret_like,
+      injection_like: preview.injection_like,
+      indexing_allowed: !preview.secret_like && !preview.injection_like && sensitivity !== 'private',
+      cross_host_allowed: !preview.secret_like && !preview.injection_like && sensitivity !== 'private',
+    },
+  };
+  if (metadata && typeof metadata === 'object') event.metadata = metadata;
+  event.event_hash = hashEvent(event);
+
+  const line = `${JSON.stringify(event)}\n`;
+  const receipt = {
+    ok: true,
+    command: 'journal add',
+    created_at: timestamp(),
+    dry_run: Boolean(dryRun),
+    durable_write: !dryRun,
+    event_id: event.event_id,
+    event_hash: event.event_hash,
+    line_hash: sha256(line),
+    line_hash_status: dryRun ? 'planned' : 'observed_after_append',
+    event_log_path: journalRel,
+    source_ids: sourceIds,
+    sensitivity,
+    redacted: event.redacted,
+    safety: event.safety,
+    writes: dryRun ? [] : [{ path: journalRel, action: 'append' }],
+  };
+  receipt.receipt_path = receiptRel;
+
+  if (!dryRun) {
+    const journalAbs = safeResolve(root, journalRel);
+    const receiptAbs = safeResolve(root, receiptRel);
+    ensureDir(path.dirname(journalAbs));
+    ensureDir(path.dirname(receiptAbs));
+    fs.writeFileSync(receiptAbs, `${JSON.stringify({
+      ...receipt,
+      ok: false,
+      pending: true,
+      line_hash_status: 'expected_pending_append',
+    }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    fs.appendFileSync(journalAbs, line, 'utf8');
+    fs.writeFileSync(receiptAbs, `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
+  }
+
+  return {
+    ok: true,
+    command: 'journal add',
+    dry_run: Boolean(dryRun),
+    durable_write: !dryRun,
+    event,
+    receipt_path: dryRun ? null : receiptRel,
+    receipt,
+  };
+}
+
+export function listJournalEvents(root, { limit = 20, type = '' } = {}) {
+  const rows = readJournalRows(root);
+  const normalizedType = type ? normalizeType(type) : '';
+  const events = rows
+    .filter((row) => row.ok)
+    .map((row) => row.event)
+    .filter((event) => !normalizedType || event.type === normalizedType)
+    .slice(-Number(limit || 20))
+    .reverse();
+  return {
+    ok: true,
+    command: 'journal list',
+    durable_write: false,
+    event_log_path: journalRel,
+    count: events.length,
+    events,
+  };
+}
+
+export function verifyJournal(root) {
+  const rows = readJournalRows(root);
+  const errors = [];
+  for (const row of rows) {
+    if (!row.ok) {
+      errors.push({ line: row.line, reason: row.reason });
+      continue;
+    }
+    const expected = hashEvent(row.event);
+    if (expected !== row.event.event_hash) {
+      errors.push({ line: row.line, event_id: row.event.event_id, reason: 'event_hash mismatch' });
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    command: 'journal verify',
+    durable_write: false,
+    event_log_path: journalRel,
+    line_count: rows.length,
+    error_count: errors.length,
+    errors,
+  };
+}
+
+function renderJournalAdd(root, args) {
+  const result = appendJournalEvent(root, {
+    type: args.type || 'note',
+    summary: args.summary || args.message || '',
+    source: args.source || '',
+    host: args.host || 'cli',
+    scope: args.scope || 'global',
+    confirm: args.confirm || '',
+    dryRun: Boolean(args['dry-run']),
+  });
+  if (args.json) return { json: true, payload: result };
+  return {
+    text: [
+      `# Neurain journal add${result.dry_run ? ' [dry-run]' : ''}`,
+      '',
+      `- OK: ${result.ok ? 'yes' : 'no'}`,
+      `- Event: ${result.event.event_id}`,
+      `- Type: ${result.event.type}`,
+      `- Durable write: ${result.durable_write ? 'yes' : 'no'}`,
+      `- Redacted: ${result.event.redacted ? 'yes' : 'no'}`,
+      result.receipt_path ? `- Receipt: ${result.receipt_path}` : '',
+    ].filter(Boolean).join('\n'),
+  };
+}
+
+function renderJournalList(root, args) {
+  const result = listJournalEvents(root, { limit: Number(args.top || args.limit || 20), type: args.type || '' });
+  if (args.json) return { json: true, payload: result };
+  return {
+    text: [
+      '# Neurain journal',
+      '',
+      `- Events: ${result.count}`,
+      '- Durable write: no',
+      '',
+      ...result.events.map((event) => [
+        `## ${event.event_id}`,
+        `- Type: ${event.type}`,
+        `- Created: ${event.created_at}`,
+        `- Sensitivity: ${event.sensitivity}`,
+        `- Prompt context allowed: ${event.prompt_context_allowed ? 'yes' : 'no'}`,
+        `- Summary: ${event.summary}`,
+      ].join('\n')),
+    ].join('\n'),
+  };
+}
+
+function renderJournalVerify(root, args) {
+  const result = verifyJournal(root);
+  if (args.json) return { json: true, payload: result };
+  return {
+    text: [
+      '# Neurain journal verify',
+      '',
+      `- OK: ${result.ok ? 'yes' : 'no'}`,
+      `- Lines: ${result.line_count}`,
+      `- Errors: ${result.error_count}`,
+    ].join('\n'),
+  };
+}
+
+function readJournalRows(root) {
+  const text = readText(safeResolve(root, journalRel), '');
+  return text.split(/\r?\n/).map((line, index) => ({ line, index })).filter((row) => row.line.trim()).map((row) => {
+    try {
+      const event = JSON.parse(row.line);
+      return { ok: true, line: row.index + 1, event };
+    } catch {
+      return { ok: false, line: row.index + 1, reason: 'invalid json' };
+    }
+  });
+}
+
+function normalizeType(value) {
+  const type = String(value || 'note').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+  if (!allowedTypes.has(type)) throw new Error(`Unsupported journal event type: ${value}`);
+  return type;
+}
+
+function normalizeSourceIds(source) {
+  if (!source) return [];
+  if (Array.isArray(source)) return source.flatMap((item) => normalizeSourceIds(item));
+  return String(source).split(',').map((item) => item.trim()).filter(Boolean).map((item) => item.replace(/\\/g, '/'));
+}
+
+function hashEvent(event) {
+  const copy = { ...event };
+  delete copy.event_hash;
+  return sha256(stableJson(copy));
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/core/labels.mjs

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { readText } from './fs.mjs';
+import { maxSensitivity } from './safety.mjs';
+
+// Default private path markers for the MARKDOWN recall corpus. Matching uses a
+// word-ish boundary (any non letter/digit bounds a marker), so `_private`,
+// `private-area-brief`, and `personal_records` are caught while a marker that
+// merely appears as a SUBSTRING of a longer word (e.g. `credential` inside
+// `credentialing-notes`) is NOT. The old engine gate used a plain substring test
+// on safety.inferSensitivityFromPath, whose markers could exclude a whole
+// legitimate knowledge folder; that is the bug this module fixes. `token` and
+// `recovery` are intentionally omitted from the markdown vocabulary (too many
+// false positives in real knowledge folders);
+// event/receipt metadata still uses safety.inferSensitivityFromPath unchanged,
+// where stricter is harmless.
+export const DEFAULT_PATH_MARKERS = [
+  'private', 'secrets?', 'credentials?', 'passwords?', 'keychain',
+  'personal[_-]?records', '\\.env',
+];
+
+const SCALAR_LINE = /^([A-Za-z0-9_-]+):\s*(.*)$/;
+
+// Parse the leading `--- ... ---` frontmatter into a flat map of scalar fields,
+// without a YAML dependency (engine has none). Only top-of-file scalars are
+// read; list and nested values are ignored because the only field we need is a
+// scalar (`sensitivity:`). Stricter than a whole-file grep, so a body that
+// merely mentions `sensitivity:` mid-document is never misread as a label.
+export function parseFrontmatter(text) {
+  const value = String(text || '');
+  if (!/^---\r?\n/.test(value)) return {};
+  const lines = value.split(/\r?\n/);
+  const out = {};
+  for (let i = 1; i < lines.length && i < 200; i += 1) {
+    if (lines[i].trim() === '---') break;
+    const match = lines[i].match(SCALAR_LINE);
+    if (match) out[match[1].toLowerCase()] = match[2].trim();
+  }
+  return out;
+}
+
+function normalizeSensitivity(value) {
+  const text = String(value || '').toLowerCase();
+  if (/\bprivate\b/.test(text)) return 'private';
+  if (/\bpublic\b/.test(text)) return 'public';
+  return 'internal';
+}
+
+// Compile marker source strings (trusted regex fragments from defaults or
+// config) into boundary-wrapped regexes. An unparseable fragment is skipped, not
+// thrown, so one bad config entry never disables sensitivity gating wholesale.
+export function compileMarkers(markers) {
+  const compiled = [];
+  for (const marker of markers || []) {
+    try {
+      compiled.push(new RegExp(`(^|[^\\p{L}\\p{N}])(${String(marker)})($|[^\\p{L}\\p{N}])`, 'iu'));
+    } catch {
+      /* skip invalid marker */
+    }
+  }
+  return compiled;
+}
+
+export function matchesPathMarker(rel, compiled) {
+  return (compiled || []).some((re) => re.test(String(rel || '')));
+}
+
+// Build a resolver that decides per-path sensitivity by STRONGEST-WINS over four
+// signals: per-file frontmatter `sensitivity:`, the area baseline from the
+// area's `_area.md` (private but not "mixed" -> whole area private, mirroring the
+// vault), configurable path markers, and a default (internal). Area baselines are
+// cached per area dir. The resolver reads files lazily; pass the already-read
+// text into sensitivityFor so the corpus walk reads each file once.
+export function createSensitivityResolver(root, recallCfg = {}) {
+  const areasDir = recallCfg.areas_dir || '10_areas';
+  const markerSources = Array.isArray(recallCfg.labels?.path_markers) && recallCfg.labels.path_markers.length
+    ? recallCfg.labels.path_markers
+    : DEFAULT_PATH_MARKERS;
+  const compiled = compileMarkers(markerSources);
+  const overrides = (recallCfg.labels && recallCfg.labels.areas) || {};
+  const def = normalizeSensitivity(recallCfg.labels?.default_sensitivity || 'internal');
+  const areaCache = new Map();
+  const areaRe = new RegExp(`^${areasDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/([^/]+)/`);
+
+  function areaBaseline(dir) {
+    if (areaCache.has(dir)) return areaCache.get(dir);
+    let result = '';
+    const override = overrides[dir];
+    if (override !== undefined) {
+      if (/\bprivate\b/i.test(String(override)) && !/\bmixed\b/i.test(String(override))) result = 'private';
+    } else {
+      const text = readText(path.join(root, areasDir, dir, '_area.md'), '');
+      const match = text.match(/^sensitivity:\s*(.+)$/im);
+      if (match && /\bprivate\b/i.test(match[1]) && !/\bmixed\b/i.test(match[1])) result = 'private';
+    }
+    areaCache.set(dir, result);
+    return result;
+  }
+
+  function sensitivityFor(rel, text) {
+    const signals = [def];
+    const fm = parseFrontmatter(text);
+    if (fm.sensitivity) signals.push(normalizeSensitivity(fm.sensitivity));
+    const areaMatch = String(rel).match(areaRe);
+    if (areaMatch) {
+      const baseline = areaBaseline(areaMatch[1]);
+      if (baseline) signals.push(baseline);
+    }
+    if (matchesPathMarker(rel, compiled)) signals.push('private');
+    return maxSensitivity(signals);
+  }
+
+  return {
+    sensitivityFor,
+    isPrivateArea: (dir) => areaBaseline(dir) === 'private',
+    markers: compiled,
+  };
+}