neurain 0.1.0-alpha.0

package/src/core/doctor.mjs

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, exists, walkFiles } from './fs.mjs';
+import { listJournalEvents, verifyJournal } from './journal.mjs';
+import { listLessons } from './lessons.mjs';
+import { recallStatus } from './recall.mjs';
+
+const required = [
+  'neurain.config.json',
+  'AGENTS.md',
+  'CLAUDE.md',
+  '00_system/neurain-startup.md',
+  '00_system/neurain/neurain-rules.md',
+  '00_system/neurain/lessons.md',
+  '00_system/neurain/events.ndjson',
+  '00_system/sessions/session-state.json',
+  '00_system/sessions/session-registry.md',
+  'wiki/index.md',
+  'wiki/log.md',
+  'raw/_inbox',
+  'output',
+];
+
+export async function doctorCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const missing = required.filter((rel) => !exists(path.join(root, rel)));
+  const config = readConfig(root);
+  const files = exists(root) ? walkFiles(root, { maxFiles: 20000 }) : [];
+  const lessons = exists(root) ? listLessons(root) : [];
+  const journal = exists(root) ? listJournalEvents(root, { limit: 5 }) : { count: 0 };
+  const journalIntegrity = exists(root) ? verifyJournal(root) : { ok: false };
+  const recall = exists(root) ? await recallStatus(root) : { sqlite_available: false, db_exists: false, row_count: 0, markdown_fallback: true };
+  const packageVersion = await version();
+  const payload = {
+    ok: exists(root) && fs.statSync(root).isDirectory() && missing.length === 0,
+    command: 'doctor',
+    root,
+    package_version: packageVersion,
+    missing,
+    file_count: files.length,
+    language_default: config.language_default || null,
+    host_connections: {
+      codex: 'run `neurain connect codex <folder>` to configure',
+      claude: 'run `neurain connect claude <folder>` to configure',
+      gemini: 'run `neurain connect gemini <folder>` to configure',
+      claude_lifecycle_hooks: 'preview with `neurain connect claude <folder> --lifecycle-hooks --dry-run`',
+      runtime: 'preview with `neurain connect runtime <folder> --dry-run`',
+    },
+    lesson_loop: {
+      registry_exists: exists(path.join(root, '00_system/neurain/lessons.md')),
+      active_lessons: lessons.length,
+      candidate_preview: 'run `neurain lessons candidates <folder>` or `neurain wrap <folder> --dry-run`',
+      promotion_available: 'cli_only_with_exact_confirmation',
+      rollback_available: true,
+    },
+    event_journal: {
+      path: '00_system/neurain/events.ndjson',
+      recent_events: journal.count || 0,
+      integrity_ok: journalIntegrity.ok,
+      write_policy: 'cli_only_with_exact_confirmation',
+    },
+    curator_loop: {
+      status_preview: 'run `neurain curator status <folder>`',
+      run_preview: 'run `neurain curator run <folder> --dry-run`',
+      write_policy: 'snapshot_then_exact_confirmation',
+      rollback_available: true,
+    },
+    recall_index: {
+      db_path: '00_system/neurain/recall.sqlite',
+      sqlite_available: recall.sqlite_available,
+      db_exists: recall.db_exists,
+      row_count: recall.row_count,
+      markdown_fallback: true,
+      rebuild: 'run `neurain recall rebuild <folder>`',
+    },
+    admin_surface: {
+      status: 'locked',
+      reason: 'The CLI alpha has no web admin page. Future admin UI must require authentication before exposing controls.',
+    },
+    backup: {
+      status: 'not_configured',
+      recommendation: 'Keep this folder in an external drive or cloud-synced backup before serious use.',
+    },
+  };
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      '# Neurain doctor',
+      '',
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Root: ${root}`,
+      `- Version: ${packageVersion}`,
+      `- Files scanned: ${files.length}`,
+      `- Missing required files: ${missing.length ? missing.join(', ') : 'none'}`,
+      `- Active lessons: ${lessons.length}`,
+      `- Journal integrity: ${payload.event_journal.integrity_ok ? 'ok' : 'not ready'}`,
+      `- Recall DB: ${payload.recall_index.db_exists ? `${payload.recall_index.row_count} rows` : 'not built, markdown fallback available'}`,
+      `- Admin surface: ${payload.admin_surface.status}`,
+      `- Backup: ${payload.backup.recommendation}`,
+    ].join('\n'),
+  };
+}
+
+function readConfig(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'neurain.config.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function version() {
+  const pkg = await import('../../package.json', { with: { type: 'json' } });
+  return pkg.default.version;
+}

package/src/core/durable.mjs

@@ -0,0 +1,96 @@
+// Shared durable-write primitives (W-B). The crash-safe + concurrency-safe write
+// layer every W-B writer routes through: a temp+fsync+rename atomic write so a
+// crash never leaves a torn file, an O_EXCL cross-process lock with stale-lock
+// reclaim so concurrent read-modify-write callers serialize instead of clobbering
+// each other, and a locked JSONL append (the engine FIXES the vault capture's
+// non-atomic append here). Faithful port of the vault neurain-utils primitives.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, readText } from './fs.mjs';
+
+export function atomicWriteText(filePath, text) {
+  ensureDir(path.dirname(filePath));
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, text);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, filePath);
+  try { const dfd = fs.openSync(path.dirname(filePath), 'r'); fs.fsyncSync(dfd); fs.closeSync(dfd); } catch { /* dir fsync best-effort */ }
+}
+
+export function atomicWriteJson(filePath, value) {
+  atomicWriteText(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+// Serialize callers on `abs` with an O_EXCL lock. Reclaims a lock older than 10
+// minutes whose owning pid is gone (so a crashed holder never wedges the file).
+export function withFileLock(abs, fn) {
+  const lockPath = `${abs}.lock`;
+  ensureDir(path.dirname(abs));
+  try {
+    const st = fs.statSync(lockPath);
+    if (Date.now() - st.mtimeMs > 600000) {
+      const pid = parseInt(String(fs.readFileSync(lockPath)).split(/\s/)[0], 10);
+      let alive = false;
+      try { process.kill(pid, 0); alive = true; } catch { /* not alive */ }
+      if (!alive) fs.unlinkSync(lockPath);
+    }
+  } catch { /* no stale lock */ }
+  let fd;
+  try {
+    fd = fs.openSync(lockPath, 'wx');
+  } catch (e) {
+    throw new Error(`locked: ${lockPath} (${e.code})`);
+  }
+  try {
+    fs.writeSync(fd, `${process.pid} ${Date.now()}`);
+    return fn();
+  } finally {
+    fs.closeSync(fd);
+    try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+  }
+}
+
+// Read a .jsonl file into rows, skipping blank and torn lines (one bad line never
+// discards the whole file). Mirrors vault_state.readJsonl but lives here so the
+// write primitives are self-contained for read-modify-write callers.
+export function readJsonlRows(abs) {
+  const out = [];
+  for (const line of readText(abs, '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try { out.push(JSON.parse(trimmed)); } catch { /* skip torn line */ }
+  }
+  return out;
+}
+
+// Append one or more rows as JSONL under the file lock. The lock is what makes
+// the append atomic against a concurrent appender or rewriter (the vault's plain
+// appendText was not serialized; this is the fix).
+export function appendJsonlLocked(abs, rows) {
+  const list = Array.isArray(rows) ? rows : [rows];
+  if (!list.length) return 0;
+  const text = `${list.map((row) => JSON.stringify(row)).join('\n')}\n`;
+  withFileLock(abs, () => {
+    ensureDir(path.dirname(abs));
+    fs.appendFileSync(abs, text, 'utf8');
+  });
+  return list.length;
+}
+
+// Read-modify-write a JSONL file under one lock: the rows are re-read INSIDE the
+// lock and the mutated set is written atomically, so a row appended between an
+// earlier read and this rewrite is never lost. `mutate(rows)` returns the next
+// row array.
+export function rewriteJsonlLocked(abs, mutate) {
+  return withFileLock(abs, () => {
+    const rows = readJsonlRows(abs);
+    const next = mutate(rows) || [];
+    atomicWriteText(abs, next.length ? `${next.map((row) => JSON.stringify(row)).join('\n')}\n` : '');
+    return next;
+  });
+}

package/src/core/envelope.mjs

@@ -0,0 +1,97 @@
+// Capture-envelope construction and source-input reading (W-B, read/pure half).
+// `makeEnvelope` is the deterministic classification + envelope builder that route
+// and plan-writeback share; it is pure (no writes) so it lives here ahead of the
+// durable capture writer (B4), which will reuse it. `readArgInput` resolves the
+// source text a command was given (--text, positional, --file, or piped stdin).
+// Faithful port of the vault neurain-utils envelope helpers.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readText, safeResolve, timestamp } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { classifyText, loadAreaIntel, loadAreaProfiles, normalizeAreaId } from './classify.mjs';
+
+export function normalizeList(value) {
+  if (!value) return [];
+  const items = Array.isArray(value) ? value : String(value).split(',');
+  return items.map((item) => String(item).trim()).filter(Boolean);
+}
+
+export const SOURCE_TYPE_FOLDERS = {
+  chat: 'chat', file: 'files', files: 'files', link: 'links', meeting: 'meetings',
+  memo: 'memos', note: 'memos', screenshot: 'screenshots', transcript: 'transcripts', web: 'web',
+};
+
+export function folderForSourceType(sourceType) {
+  return SOURCE_TYPE_FOLDERS[String(sourceType || 'memo').toLowerCase()] || 'memos';
+}
+
+export function slugify(value, fallback = 'untitled') {
+  const out = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9가-힣]+/gi, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+  return out || fallback;
+}
+
+export function quoteYaml(value) {
+  return JSON.stringify(String(value || ''));
+}
+
+// Render the raw-source markdown for a capture: frontmatter + the full envelope
+// JSON block + the raw body. Byte-faithful to the vault renderCaptureMarkdown.
+export function renderCaptureMarkdown(envelope, body) {
+  const safeBody = String(body || '').trimEnd();
+  return `---\nsource_id: ${envelope.source_id}\ntitle: ${quoteYaml(envelope.title)}\ntype: raw_source\nsource_type: ${envelope.source_type}\nareas: [${envelope.area_candidates.join(', ')}]\nsensitivity: ${envelope.sensitivity}\nstatus: ${envelope.status}\ncaptured: ${envelope.captured_at}\n---\n\n# ${envelope.title}\n\n## Capture Envelope\n\n\`\`\`json\n${JSON.stringify(envelope, null, 2)}\n\`\`\`\n\n## Raw Content\n\n${safeBody}\n`;
+}
+
+// Build a capture envelope from raw text. `root` anchors registry-driven routing;
+// `overrides` may pin area(s), sensitivity, intent, or requiresUserDecision. Pure:
+// classification reads the registry/area files but nothing is written.
+export function makeEnvelope(root, { sourceId, sourceType, title, text, status = 'planned', overrides = {} }, opts = {}) {
+  const vaultCfg = opts.vaultCfg || vaultConfig(root);
+  const intel = opts.intel || loadAreaIntel(root, vaultCfg);
+  const profiles = opts.profiles || loadAreaProfiles(root, vaultCfg, intel);
+  const route = classifyText(root, text, overrides, { vaultCfg, intel, profiles });
+  const areaCandidates = normalizeList(overrides.area || overrides.areas || route.area_candidates).map((a) => normalizeAreaId(root, a, vaultCfg));
+  const domainCandidates = normalizeList(overrides.domain || overrides.domains || route.domain_candidates);
+  const entityCandidates = normalizeList(overrides.entity || overrides.entities || route.entity_candidates);
+  return {
+    source_id: sourceId,
+    title,
+    source_type: sourceType,
+    area_candidates: areaCandidates,
+    domain_candidates: domainCandidates,
+    entity_candidates: entityCandidates,
+    sensitivity: overrides.sensitivity || route.sensitivity,
+    write_intent: overrides.intent || route.write_intent,
+    status,
+    compiled_to: [],
+    requires_user_decision: Boolean(overrides.requiresUserDecision || route.requires_user_decision),
+    captured_at: timestamp(),
+  };
+}
+
+// Resolve the source text a command was handed. Precedence mirrors the vault:
+// explicit --text, then positional tokens after the root, then --file (root-
+// relative or absolute), then piped stdin. Stdin is only read when not a TTY, so
+// an interactive CLI never blocks and spawned tests with a closed stdin get ''.
+export function readArgInput(args, root) {
+  if (typeof args.text === 'string') return args.text;
+  const positional = args._.slice(1).join(' ').trim();
+  if (positional) return positional;
+  if (args.file) {
+    const target = path.isAbsolute(String(args.file)) ? String(args.file) : safeResolve(root, String(args.file));
+    return readText(target, '');
+  }
+  if (!process.stdin.isTTY) {
+    try {
+      return fs.readFileSync(0, 'utf8');
+    } catch {
+      return '';
+    }
+  }
+  return '';
+}

package/src/core/flush.mjs

@@ -0,0 +1,190 @@
+// `flush` and `session-flush` commands (W-B, read-only). Both read the flat root
+// writeback queue and produce a flush PLAN — never a write. `flush` groups all
+// pending items by Light/Standard/Full scope; `session-flush` scopes to one
+// session at a requested level, separating allowed vs blocked items and flagging
+// target conflicts. Faithful port of the vault neurain-flush / neurain-session-
+// flush tools (nondeterministic timing fields are intentionally dropped; parity
+// normalizes them). The actual queue writes belong to a later increment.
+import path from 'node:path';
+import { absPath } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { loadSessionState, readJsonl } from './vault_state.mjs';
+
+const FLUSH_GUIDANCE = [
+  'Flush only reviews pending candidates already in the writeback queue.',
+  'Direct file edits do not appear as Flush items because they are already applied.',
+  'Use Pulse when the goal is to let other sessions know about the latest context.',
+  'Use Save or Compile first when new material should become a queued canonical update.',
+];
+
+function classifyScope(item) {
+  if (item.requires_user_decision || item.sensitivity === 'private') return 'Full';
+  if (['remember', 'update_current', 'create_task', 'output_request'].includes(item.write_intent)) return 'Standard';
+  return 'Light';
+}
+
+export async function flushCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const queueRel = args.queue ? String(args.queue) : vaultCfg.writeback_queue;
+  const items = readJsonl(path.join(root, queueRel)).filter((item) => item.status === 'pending');
+
+  const groups = { Light: [], Standard: [], Full: [] };
+  for (const item of items) {
+    groups[classifyScope(item)].push({
+      source_id: item.source_id,
+      title: item.title,
+      raw_path: item.raw_path,
+      sensitivity: item.sensitivity,
+      write_intent: item.write_intent,
+      requires_user_decision: item.requires_user_decision,
+    });
+  }
+
+  const payload = {
+    ok: true,
+    command: 'flush',
+    durable_write: false,
+    queue: queueRel,
+    pending: items.length,
+    groups,
+    next_action:
+      groups.Full.length > 0
+        ? 'Ask for confirmation on Full items before mutating wiki or memory.'
+        : groups.Standard.length > 0
+          ? 'Compile Standard items into source summaries and indexes.'
+          : groups.Light.length > 0
+            ? 'Apply Light metadata or log-only updates.'
+            : 'Nothing pending. Use Pulse for cross-session notice, or Save or Compile before Flush for new material.',
+    guidance: FLUSH_GUIDANCE,
+  };
+
+  if (args.json) return { json: true, payload };
+  const lines = ['# Flush Plan', '', `- Pending: ${payload.pending}`];
+  for (const scope of ['Full', 'Standard', 'Light']) lines.push(`- ${scope}: ${payload.groups[scope].length}`);
+  lines.push(`- Next action: ${payload.next_action}`);
+  if (payload.pending === 0) {
+    lines.push('', '## Guidance', '');
+    for (const line of payload.guidance) lines.push(`- ${line}`);
+  }
+  return { text: lines.join('\n') };
+}
+
+function summarizeRow(row) {
+  return {
+    source_id: row.source_id || '',
+    title: row.title || '',
+    flush_level: row.flush_level || '',
+    target_layer: row.target_layer || '',
+    target_path: row.target_path || '',
+    raw_path: row.raw_path || '',
+    requires_user_decision: Boolean(row.requires_user_decision),
+  };
+}
+
+function inferRowLevel(row) {
+  if (row.requires_user_decision || row.sensitivity === 'private') return 'full';
+  if (row.write_intent === 'evidence_only') return 'light';
+  return 'standard';
+}
+
+function isAllowedAtLevel(row, requestedLevel) {
+  if (row.requires_user_decision) return requestedLevel === 'full';
+  const rowLevel = String(row.flush_level || inferRowLevel(row)).toLowerCase();
+  if (requestedLevel === 'light') return rowLevel === 'light';
+  if (requestedLevel === 'standard') {
+    return ['light', 'standard'].includes(rowLevel) && !['current', 'fact_ledger', 'task_memory'].includes(row.target_layer);
+  }
+  return true;
+}
+
+function blockReason(row, requestedLevel) {
+  if (row.requires_user_decision) return 'requires user decision';
+  if (requestedLevel === 'light') return 'needs standard or full flush';
+  if (['current', 'fact_ledger', 'task_memory'].includes(row.target_layer)) return 'canonical state layer requires Full Flush';
+  return 'blocked by flush level policy';
+}
+
+function detectConflicts(items) {
+  const byTarget = new Map();
+  for (const row of items) {
+    const key = `${row.target_layer || ''}:${row.target_path || ''}`;
+    if (!row.target_layer || !row.target_path) continue;
+    const current = byTarget.get(key) || [];
+    current.push(row);
+    byTarget.set(key, current);
+  }
+  return [...byTarget.entries()]
+    .filter(([, rowsForTarget]) => rowsForTarget.length > 1)
+    .map(([target, rowsForTarget]) => ({
+      target,
+      count: rowsForTarget.length,
+      source_ids: rowsForTarget.map((row) => row.source_id || row.queue_id || '').filter(Boolean),
+      policy: 'queue_first',
+      requires_user_decision: true,
+    }));
+}
+
+export async function sessionFlushCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const sessionId = String(args['session-id'] || '');
+  const level = String(args.level || 'standard').toLowerCase();
+
+  if (!sessionId) return done(args, { ok: false, command: 'session-flush', durable_write: false, error: 'Missing --session-id.' });
+  if (!['light', 'standard', 'full'].includes(level)) {
+    return done(args, { ok: false, command: 'session-flush', durable_write: false, error: 'Invalid --level. Use light, standard, or full.' });
+  }
+  let state = { sessions: {} };
+  try { state = loadSessionState(root, vaultCfg); } catch (error) {
+    return done(args, { ok: false, command: 'session-flush', durable_write: false, error: error.message });
+  }
+  if (!(state.sessions || {})[sessionId]) {
+    return done(args, { ok: false, command: 'session-flush', durable_write: false, error: `unknown session "${sessionId}"` });
+  }
+
+  const queueRel = args.queue ? String(args.queue) : vaultCfg.writeback_queue;
+  const rows = readJsonl(path.join(root, queueRel));
+  const pending = rows.filter((row) => row.session_id === sessionId && row.status === 'pending');
+  const conflicts = detectConflicts(pending);
+  const allowed = pending.filter((row) => isAllowedAtLevel(row, level));
+  const blocked = pending.filter((row) => !isAllowedAtLevel(row, level));
+
+  const payload = {
+    ok: true,
+    command: 'session-flush',
+    durable_write: false,
+    session_id: sessionId,
+    level,
+    queue_path: queueRel,
+    pending_count: pending.length,
+    allowed_count: allowed.length,
+    blocked_count: blocked.length,
+    conflicts,
+    allowed: allowed.map(summarizeRow),
+    blocked: blocked.map((row) => ({ ...summarizeRow(row), reason: blockReason(row, level) })),
+    mutates_canonical: false,
+    note:
+      level === 'full'
+        ? 'Full Flush requires user confirmation before current, fact ledger, task memory, supersede, or conflict writes.'
+        : 'This v1 command prepares a session-scoped flush plan. The agent performs the compiled markdown write, then closes queue rows with complete.',
+  };
+  return done(args, payload);
+}
+
+function done(args, payload) {
+  if (args.json) return { json: true, payload };
+  if (!payload.ok) return { text: `# Session Flush Plan\n\n- ${payload.error}` };
+  const lines = [
+    '# Session Flush Plan',
+    '',
+    `- Session: ${payload.session_id}`,
+    `- Level: ${payload.level}`,
+    `- Pending: ${payload.pending_count}`,
+    `- Allowed: ${payload.allowed_count}`,
+    `- Blocked: ${payload.blocked_count}`,
+    `- Conflicts: ${payload.conflicts.length}`,
+    '- Mutates canonical: no',
+  ];
+  return { text: lines.join('\n') };
+}

package/src/core/fs.mjs

@@ -0,0 +1,121 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const GENERATED_NAMES = new Set(['.git', 'node_modules', '.next', 'out', '.vercel', '.DS_Store', '.cache', '.neurain-staging']);
+
+export function absPath(input, fallback = process.cwd()) {
+  return path.resolve(String(input || fallback));
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function exists(file) {
+  return fs.existsSync(file);
+}
+
+export function readText(file, fallback = '') {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeFileNoOverwrite(file, content, { dryRun = false, created = [], skipped = [] } = {}) {
+  if (fs.existsSync(file)) {
+    skipped.push(file);
+    return { created, skipped };
+  }
+  if (!dryRun) {
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(file, content, 'utf8');
+  }
+  created.push(file);
+  return { created, skipped };
+}
+
+export function safeResolve(root, relPath) {
+  const rootAbs = path.resolve(root);
+  const target = path.resolve(rootAbs, String(relPath));
+  if (target !== rootAbs && !target.startsWith(`${rootAbs}${path.sep}`)) {
+    throw new Error(`Refusing path outside root: ${relPath}`);
+  }
+  return target;
+}
+
+export function relPath(root, file) {
+  return path.relative(root, file).split(path.sep).join('/');
+}
+
+export function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+export function slug(value, fallback = 'general') {
+  return String(value || fallback)
+    .toLowerCase()
+    .replace(/^_+/, '')
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || fallback;
+}
+
+export function timestamp() {
+  const now = new Date();
+  const parts = new Intl.DateTimeFormat('en-CA', {
+    timeZone: 'Asia/Seoul',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  }).formatToParts(now);
+  const p = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+  return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}+09:00`;
+}
+
+export function compactStamp() {
+  return timestamp().replace(/[:+]/g, '').replace('T', '-');
+}
+
+export function walkFiles(root, { includeRaw = true, maxFiles = 10000 } = {}) {
+  const out = [];
+  function rec(dir) {
+    if (out.length >= maxFiles) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (out.length >= maxFiles) return;
+      const abs = path.join(dir, entry.name);
+      const rel = relPath(root, abs);
+      if (GENERATED_NAMES.has(entry.name) || generatedPath(rel)) continue;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        rec(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!includeRaw && rel.startsWith('raw/')) continue;
+      out.push(abs);
+    }
+  }
+  rec(root);
+  return out;
+}
+
+export function generatedPath(rel) {
+  return /(^|\/)(node_modules|\.git|\.next|out|\.vercel|\.cache)(\/|$)/.test(rel);
+}
+
+export function isTextFile(file) {
+  return /\.(md|txt|json|yml|yaml|toml|env|js|mjs|ts|tsx|py|html|css)$/i.test(file);
+}