@ekkos/cli 1.3.7 → 1.3.8

package/dist/local/living-docs-manager.js

@@ -0,0 +1,1084 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalLivingDocsManager = void 0;
+const fs_1 = require("fs");
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const os_1 = require("os");
+const scan_js_1 = require("../commands/scan.js");
+const stack_detection_js_1 = require("./stack-detection.js");
+const language_config_js_1 = require("./language-config.js");
+// ── Language-adaptive defaults (overridden per-system when stack is detected) ──
+const DEFAULT_EXCLUDED_DIRS = new Set([
+    ...language_config_js_1.BASE_EXCLUDED_DIRS,
+    'node_modules', '.next', 'dist', 'out', 'build', '.turbo', '.cache',
+    '.github', '.vscode', '.idea', '.claude', '.windsurf',
+    'coverage', '__pycache__', '.pytest_cache', '.mypy_cache',
+    'vendor', '.vercel', '.svelte-kit', 'target', 'tmp', 'temp',
+    'logs', 'downloads', '.venv', 'venv', '.tox', '.eggs',
+    '.gradle', '.mvn', '.bundle',
+]);
+const EXCLUDED_FILES = new Set([
+    'ekkOS_CONTEXT.md',
+    '.DS_Store',
+]);
+const DEFAULT_SOURCE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.py', '.rs', '.go', '.java', '.kt', '.swift',
+    '.rb', '.ex', '.exs', '.php', '.cs', '.dart',
+    '.c', '.cpp', '.h', '.hpp',
+    '.sql', '.json', '.yml', '.yaml', '.toml', '.md',
+]);
+const DEFAULT_KEY_FILE_NAMES = [
+    'package.json', 'README.md', 'readme.md',
+    'index.ts', 'index.tsx', 'index.js', 'main.ts', 'server.ts', 'app.ts', 'mod.ts',
+    'pyproject.toml', 'requirements.txt', 'main.py', 'app.py', 'manage.py',
+    'Cargo.toml', 'main.rs', 'lib.rs',
+    'go.mod', 'main.go',
+    'Gemfile', 'config.ru',
+    'pom.xml', 'build.gradle',
+    'pubspec.yaml', 'mix.exs', 'composer.json',
+];
+const ENV_VAR_REGEXES = [
+    /\bprocess\.env\.([A-Z0-9_]+)/g,
+    /\bimport\.meta\.env\.([A-Z0-9_]+)/g,
+    /\benv\.([A-Z0-9_]+)/g,
+    /\bgetEnvVar\(\s*['"`]([A-Z0-9_]+)['"`]\s*\)/g,
+];
+const LOCAL_CONTEXT_TEMPLATE_VERSION = 'local-mechanical-v4';
+/**
+ * Cooldown period for full system discovery + compile on startup.
+ * If the last successful scan completed within this window, skip the expensive
+ * discoverSystems/buildSnapshot/compileStaleSystems work and just start the watcher.
+ * This avoids redundant multi-second scans when the user runs `ekkos run` many times a day.
+ * Default: 10 minutes. Override via EKKOS_LIVING_DOCS_COOLDOWN_MS env var.
+ */
+const SCAN_COOLDOWN_MS = parseInt(process.env.EKKOS_LIVING_DOCS_COOLDOWN_MS || String(10 * 60 * 1000), 10);
+function normalizePath(input) {
+    return input.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+function matchesDirectoryPath(filePath, directoryPath) {
+    const normalizedFile = normalizePath(filePath);
+    const normalizedDirectory = normalizePath(directoryPath);
+    if (!normalizedDirectory || normalizedDirectory === '.')
+        return true;
+    return normalizedFile === normalizedDirectory || normalizedFile.startsWith(`${normalizedDirectory}/`);
+}
+/**
+ * Convert ISO timestamp to human-readable: "Mar 16, 2:52 PM" or "Mar 14" (older).
+ */
+function formatReadableDate(isoTimestamp) {
+    try {
+        const date = new Date(isoTimestamp);
+        if (isNaN(date.getTime()))
+            return isoTimestamp;
+        const now = new Date();
+        const diffDays = Math.floor((now.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
+        const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+        const month = months[date.getMonth()];
+        const day = date.getDate();
+        if (diffDays === 0) {
+            // Today: "Today, 2:52 PM"
+            const hours = date.getHours();
+            const minutes = date.getMinutes().toString().padStart(2, '0');
+            const ampm = hours >= 12 ? 'PM' : 'AM';
+            const h12 = hours % 12 || 12;
+            return `Today, ${h12}:${minutes} ${ampm}`;
+        }
+        else if (diffDays === 1) {
+            return 'Yesterday';
+        }
+        else if (diffDays < 7) {
+            return `${diffDays} days ago`;
+        }
+        else {
+            return `${month} ${day}`;
+        }
+    }
+    catch {
+        return isoTimestamp;
+    }
+}
+/**
+ * Extract the purpose/description from README or package.json.
+ * This tells humans and agents what this system actually DOES.
+ */
+function extractPurpose(files) {
+    // Try README first — first paragraph after the title
+    const readme = files.find(f => (0, path_1.basename)(f.relativePath).toLowerCase() === 'readme.md');
+    if (readme?.content) {
+        const lines = readme.content.split('\n');
+        let pastTitle = false;
+        for (const line of lines) {
+            if (line.startsWith('#')) {
+                pastTitle = true;
+                continue;
+            }
+            if (pastTitle && line.trim().length > 20) {
+                return line.trim().slice(0, 300);
+            }
+        }
+    }
+    // Try package.json description
+    const pkgJson = files.find(f => (0, path_1.basename)(f.relativePath) === 'package.json');
+    if (pkgJson?.content) {
+        try {
+            const pkg = JSON.parse(pkgJson.content);
+            if (pkg.description && pkg.description.length > 10) {
+                return pkg.description.slice(0, 300);
+            }
+        }
+        catch { /* ignore */ }
+    }
+    // Try first JSDoc comment in entry file
+    const entry = files.find(f => ['index.ts', 'index.tsx', 'main.ts', 'server.ts', 'app.ts'].includes((0, path_1.basename)(f.relativePath)));
+    if (entry?.content) {
+        const jsdocMatch = entry.content.match(/\/\*\*\s*\n\s*\*\s*(.+?)(?:\n|\*\/)/);
+        if (jsdocMatch && jsdocMatch[1].length > 15) {
+            return jsdocMatch[1].trim().slice(0, 300);
+        }
+    }
+    return null;
+}
+/**
+ * Extract key modules — top-level directories and important files.
+ * Summarizes what each sub-directory contains based on file names.
+ */
+function extractKeyModules(files, systemDir) {
+    // Group files by first-level subdirectory
+    const dirFiles = new Map();
+    for (const f of files) {
+        const parts = f.relativePath.split('/');
+        if (parts.length >= 2) {
+            const dir = parts[0];
+            if (!dirFiles.has(dir))
+                dirFiles.set(dir, []);
+            dirFiles.get(dir).push((0, path_1.basename)(f.relativePath));
+        }
+    }
+    const modules = [];
+    for (const [dir, fileNames] of dirFiles) {
+        if (fileNames.length === 0)
+            continue;
+        const count = fileNames.length;
+        const exts = [...new Set(fileNames.map(f => (0, path_1.extname)(f)).filter(Boolean))].slice(0, 3).join(', ');
+        // Try to infer what this directory does from its name
+        const desc = inferDirPurpose(dir, count, exts, fileNames);
+        modules.push({ path: dir + '/', description: desc });
+    }
+    // Also include standalone important files at root level
+    for (const f of files) {
+        if (!f.relativePath.includes('/') && ['index.ts', 'server.ts', 'main.ts', 'app.ts', 'cli.ts'].includes((0, path_1.basename)(f.relativePath))) {
+            const firstComment = f.content.match(/\/\*\*?\s*\n?\s*\*?\s*(.+?)(?:\n|\*\/)/);
+            const desc = firstComment ? firstComment[1].trim().slice(0, 80) : 'Entry point';
+            modules.push({ path: (0, path_1.basename)(f.relativePath), description: desc });
+        }
+    }
+    return modules.slice(0, 12);
+}
+function inferDirPurpose(dir, fileCount, exts, fileNames) {
+    const name = dir.toLowerCase();
+    const hasTests = fileNames.some(f => /test|spec/i.test(f));
+    const knownDirs = {
+        'commands': 'CLI commands',
+        'lib': 'shared utilities and helpers',
+        'utils': 'utility functions',
+        'types': 'TypeScript type definitions',
+        'hooks': 'React hooks',
+        'components': 'UI components',
+        'api': 'API routes and handlers',
+        'middleware': 'request middleware',
+        'routes': 'route handlers',
+        'models': 'data models',
+        'services': 'business logic services',
+        'config': 'configuration',
+        'constants': 'constant values',
+        'scripts': 'utility scripts',
+        'tests': 'test suites',
+        'migrations': 'database migrations',
+        'cron': 'scheduled jobs',
+        'workers': 'background workers',
+        'cache': 'caching layer',
+        'auth': 'authentication',
+        'database': 'database access',
+        'embeddings': 'embedding generation',
+        'layers': 'memory layer implementations',
+        'capture': 'data capture and recording',
+        'local': 'local-only features',
+        'deploy': 'deployment tooling',
+    };
+    if (knownDirs[name])
+        return `${knownDirs[name]} (${fileCount} files)`;
+    return `${fileCount} ${exts || ''} files${hasTests ? ' (includes tests)' : ''}`.trim();
+}
+function sha256(text) {
+    return (0, crypto_1.createHash)('sha256').update(text).digest('hex');
+}
+function isWatchableFile(relativePath) {
+    const normalized = normalizePath(relativePath);
+    if (!normalized)
+        return false;
+    const parts = normalized.split('/');
+    for (const part of parts.slice(0, -1)) {
+        if (DEFAULT_EXCLUDED_DIRS.has(part))
+            return false;
+        if (part.startsWith('.'))
+            return false;
+    }
+    const name = parts[parts.length - 1];
+    if (EXCLUDED_FILES.has(name))
+        return false;
+    if (name.startsWith('.'))
+        return false;
+    if (name.endsWith('.log') || name.endsWith('.tmp') || name.endsWith('.swp'))
+        return false;
+    return true;
+}
+function formatDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+function escapeInline(value) {
+    return value.replace(/\r?\n/g, ' ').trim();
+}
+function describeRuntime(extCounts) {
+    const ordered = [...extCounts.entries()].sort((a, b) => b[1] - a[1]);
+    if (ordered.length === 0)
+        return 'Unknown';
+    const top = ordered[0][0];
+    if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(top))
+        return 'TypeScript / JavaScript';
+    if (top === '.py')
+        return 'Python';
+    if (top === '.rs')
+        return 'Rust';
+    if (top === '.go')
+        return 'Go';
+    if (top === '.sql')
+        return 'SQL / database scripts';
+    return ordered
+        .slice(0, 3)
+        .map(([ext]) => ext.replace(/^\./, '').toUpperCase())
+        .join(', ');
+}
+function extractDependencies(packageJsonPath) {
+    if (!(0, fs_1.existsSync)(packageJsonPath))
+        return [];
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, 'utf-8'));
+        return [
+            ...Object.keys(pkg.dependencies || {}),
+            ...Object.keys(pkg.devDependencies || {}),
+        ].slice(0, 8);
+    }
+    catch {
+        return [];
+    }
+}
+function extractEnvVars(contents) {
+    const vars = new Set();
+    for (const content of contents) {
+        for (const regex of ENV_VAR_REGEXES) {
+            regex.lastIndex = 0;
+            let match;
+            while ((match = regex.exec(content)) !== null) {
+                if (match[1])
+                    vars.add(match[1]);
+            }
+        }
+    }
+    return [...vars].sort().slice(0, 20);
+}
+function readRecentGitChanges(repoRoot, directoryPath, timeZone) {
+    try {
+        const scope = directoryPath === '.' ? '.' : directoryPath;
+        // Use %s (subject) + --stat scoped to this directory for richer context.
+        // Format: epoch\tsubject\tfiles-changed summary
+        const output = (0, child_process_1.execSync)(`git -C ${JSON.stringify(repoRoot)} log --max-count=10 --pretty=format:"%ct%x09%s%x09%b" --stat -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 64 }).trim();
+        if (!output)
+            return [];
+        // Parse: format is "epoch\tsubject\tbody" followed by --stat lines per commit.
+        // Commits are separated by blank lines between stat block and next header.
+        const entries = [];
+        const blocks = output.split(/\n(?="\d+\t)/);
+        for (const block of blocks) {
+            const lines = block.split('\n');
+            const header = (lines[0] || '').replace(/^"|"$/g, '');
+            const parts = header.split('\t');
+            const epochSeconds = parts[0];
+            const subject = parts[1] || '';
+            // Body is the "why" — commit message body after the subject line
+            const body = (parts[2] || '').trim();
+            const epochMs = Number(epochSeconds || '0') * 1000;
+            if (!epochMs)
+                continue;
+            // Extract changed file names from stat lines (e.g. " src/commands/run.ts | 42 +++---")
+            const changedFiles = [];
+            for (let i = 1; i < lines.length; i++) {
+                const statMatch = lines[i].match(/^\s*(.+?)\s*\|\s*\d+/);
+                if (statMatch) {
+                    const filePath = statMatch[1].trim();
+                    if (scope === '.' || filePath.startsWith(scope + '/') || filePath.startsWith(scope.replace(/^\.\//, '') + '/')) {
+                        const shortName = filePath.split('/').pop() || filePath;
+                        changedFiles.push(shortName);
+                    }
+                }
+            }
+            const timestamp = formatZonedTimestamp(new Date(epochMs), timeZone);
+            // Build rich message: subject + files + body (why)
+            let message = subject || 'Updated local code';
+            if (changedFiles.length > 0) {
+                message += ` — files: ${changedFiles.slice(0, 5).join(', ')}${changedFiles.length > 5 ? ` +${changedFiles.length - 5} more` : ''}`;
+            }
+            // Include first line of body as the "why" if it exists and isn't just repeating the subject
+            if (body && !body.toLowerCase().startsWith(subject.toLowerCase().slice(0, 20))) {
+                const bodyFirstLine = body.split('\n')[0].slice(0, 120);
+                if (bodyFirstLine.length > 10) {
+                    message += ` | ${bodyFirstLine}`;
+                }
+            }
+            entries.push({
+                date: timestamp || formatDate(new Date()),
+                timestamp,
+                message,
+            });
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+function parseStoredFingerprint(markdown) {
+    const match = markdown.match(/^invalidation_fingerprint:\s*(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+function parseStoredTemplateVersion(markdown) {
+    const match = markdown.match(/^compiler_template_version:\s*(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+function isValidTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone }).format(new Date());
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveUserTimeZone(preferred) {
+    const candidates = [
+        preferred,
+        process.env.EKKOS_USER_TIMEZONE,
+        process.env.TZ,
+        Intl.DateTimeFormat().resolvedOptions().timeZone,
+        'UTC',
+    ];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        const trimmed = candidate.trim();
+        if (!trimmed)
+            continue;
+        if (isValidTimeZone(trimmed))
+            return trimmed;
+    }
+    return 'UTC';
+}
+function formatZonedTimestamp(value, timeZone) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return new Date().toISOString();
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(date);
+    const map = Object.fromEntries(parts
+        .filter(part => part.type !== 'literal')
+        .map(part => [part.type, part.value]));
+    const asUtc = Date.UTC(Number(map.year), Number(map.month) - 1, Number(map.day), Number(map.hour), Number(map.minute), Number(map.second), date.getUTCMilliseconds());
+    const offsetMinutes = Math.round((asUtc - date.getTime()) / 60000);
+    const zoned = new Date(date.getTime() + offsetMinutes * 60000);
+    const sign = offsetMinutes >= 0 ? '+' : '-';
+    const absOffset = Math.abs(offsetMinutes);
+    const pad = (num, width = 2) => num.toString().padStart(width, '0');
+    return [
+        `${pad(zoned.getUTCFullYear(), 4)}-${pad(zoned.getUTCMonth() + 1)}-${pad(zoned.getUTCDate())}`,
+        `T${pad(zoned.getUTCHours())}:${pad(zoned.getUTCMinutes())}:${pad(zoned.getUTCSeconds())}.${pad(zoned.getUTCMilliseconds(), 3)}`,
+        `${sign}${pad(Math.floor(absOffset / 60))}:${pad(absOffset % 60)}`,
+    ].join('');
+}
+class LocalLivingDocsManager {
+    constructor(options) {
+        this.scopePath = '.';
+        this.systems = [];
+        this.watcher = null;
+        this.pollTimer = null;
+        this.flushTimer = null;
+        this.initialCompilePromise = null;
+        this.snapshot = new Map();
+        this.pendingFiles = new Set();
+        this.compileChain = Promise.resolve();
+        this.stopped = false;
+        this.targetPath = (0, path_1.resolve)(options.targetPath);
+        this.apiUrl = options.apiUrl;
+        this.apiKey = options.apiKey;
+        this.timeZone = resolveUserTimeZone(options.timeZone);
+        this.pollIntervalMs = options.pollIntervalMs ?? 5000;
+        this.flushDebounceMs = options.flushDebounceMs ?? 2500;
+        this.onLog = options.onLog;
+        this.repoRoot = this.targetPath;
+        this.watchRoot = this.targetPath;
+    }
+    start() {
+        // Check if a recent scan already ran (avoids redundant multi-second scans on repeated `ekkos run`)
+        // OS-agnostic cache location — works for Python, Rust, Go, etc. (not Node-specific)
+        const ekkosCache = (0, path_1.join)((0, os_1.homedir)(), '.ekkos', 'cache');
+        const repoHash = (0, crypto_1.createHash)('md5').update(this.targetPath).digest('hex').slice(0, 12);
+        const markerPath = (0, path_1.join)(ekkosCache, `living-docs-last-scan-${repoHash}`);
+        let skipFullScan = false;
+        try {
+            if ((0, fs_1.existsSync)(markerPath)) {
+                const lastScanMs = Number((0, fs_1.readFileSync)(markerPath, 'utf-8').trim());
+                if (Date.now() - lastScanMs < SCAN_COOLDOWN_MS) {
+                    skipFullScan = true;
+                    this.log(`Skipping full scan — last scan was ${Math.round((Date.now() - lastScanMs) / 1000)}s ago (cooldown: ${SCAN_COOLDOWN_MS / 1000}s)`);
+                }
+            }
+        }
+        catch { /* marker missing or unreadable — run full scan */ }
+        if (skipFullScan) {
+            // Still need systems list for the watcher, but skip seeding + compile
+            this.refreshSystems(false);
+            this.snapshot = this.buildSnapshot();
+            this.startWatcher();
+            // No full compile, but still sync server-compiled docs (fast API call)
+            this.enqueue(() => this.syncServerCompiledDocs());
+        }
+        else {
+            this.refreshSystems(true);
+            this.snapshot = this.buildSnapshot();
+            this.startWatcher();
+            this.initialCompilePromise = this.enqueue(async () => {
+                // 1. Pull server-compiled (Gemini) docs first — they're richer
+                await this.syncServerCompiledDocs();
+                // 2. Then fill gaps with local mechanical compile
+                await this.compileStaleSystems('initial local compile');
+                // Write marker on successful scan
+                try {
+                    if (!(0, fs_1.existsSync)(ekkosCache))
+                        (0, fs_1.mkdirSync)(ekkosCache, { recursive: true });
+                    (0, fs_1.writeFileSync)(markerPath, String(Date.now()));
+                }
+                catch { /* non-fatal */ }
+            });
+        }
+    }
+    stop() {
+        this.stopped = true;
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    log(message) {
+        this.onLog?.(`[LivingDocs:Local] ${message}`);
+    }
+    enqueue(task) {
+        this.compileChain = this.compileChain
+            .then(task)
+            .catch(err => this.log(`Task failed: ${err.message}`));
+        return this.compileChain;
+    }
+    refreshSystems(seedRemote) {
+        const discovered = (0, scan_js_1.discoverSystems)(this.targetPath, { scopeToTarget: true });
+        this.repoRoot = discovered.repoRoot;
+        this.watchRoot = discovered.targetRoot;
+        this.scopePath = discovered.scopePath;
+        this.systems = discovered.systems;
+        this.log(`Discovered ${this.systems.length} systems for ${this.watchRoot}` +
+            (this.scopePath === '.' ? ` within ${this.repoRoot}` : ` (scope: ${this.scopePath})`));
+        if (seedRemote && this.apiUrl && this.apiKey) {
+            void (0, scan_js_1.seedSystems)({
+                systems: this.systems,
+                apiUrl: this.apiUrl,
+                apiKey: this.apiKey,
+                compile: false,
+            })
+                .then(result => {
+                this.log(`Seeded ${result.total} systems to platform registry`);
+            })
+                .catch(err => {
+                this.log(`Registry seed skipped: ${err.message}`);
+            });
+        }
+    }
+    startWatcher() {
+        try {
+            this.watcher = (0, fs_1.watch)(this.watchRoot, { recursive: true }, (_eventType, fileName) => {
+                if (this.stopped || !fileName)
+                    return;
+                const changedPath = (0, path_1.resolve)(this.watchRoot, String(fileName));
+                const normalized = normalizePath((0, path_1.relative)(this.repoRoot, changedPath));
+                if (!normalized || normalized.startsWith('..'))
+                    return;
+                if (!isWatchableFile(normalized))
+                    return;
+                this.pendingFiles.add(normalized);
+                this.scheduleFlush();
+            });
+            this.log('Using native recursive file watcher');
+            return;
+        }
+        catch (err) {
+            this.log(`Native watcher unavailable, falling back to polling: ${err.message}`);
+        }
+        this.pollTimer = setInterval(() => {
+            if (this.stopped)
+                return;
+            const nextSnapshot = this.buildSnapshot();
+            const changed = new Set();
+            for (const [file, sig] of nextSnapshot.entries()) {
+                if (this.snapshot.get(file) !== sig)
+                    changed.add(file);
+            }
+            for (const file of this.snapshot.keys()) {
+                if (!nextSnapshot.has(file))
+                    changed.add(file);
+            }
+            this.snapshot = nextSnapshot;
+            if (changed.size === 0)
+                return;
+            for (const file of changed)
+                this.pendingFiles.add(file);
+            this.scheduleFlush();
+        }, this.pollIntervalMs);
+        this.log(`Polling for local changes every ${this.pollIntervalMs}ms`);
+    }
+    buildSnapshot() {
+        const snapshot = new Map();
+        const walk = (dirPath) => {
+            let entries;
+            try {
+                entries = (0, fs_1.readdirSync)(dirPath);
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const fullPath = (0, path_1.join)(dirPath, entry);
+                let stats;
+                try {
+                    stats = (0, fs_1.statSync)(fullPath);
+                }
+                catch {
+                    continue;
+                }
+                const relativePath = normalizePath((0, path_1.relative)(this.repoRoot, fullPath));
+                if (stats.isDirectory()) {
+                    if (DEFAULT_EXCLUDED_DIRS.has(entry) || entry.startsWith('.'))
+                        continue;
+                    walk(fullPath);
+                    continue;
+                }
+                if (!isWatchableFile(relativePath))
+                    continue;
+                snapshot.set(relativePath, `${stats.mtimeMs}:${stats.size}`);
+            }
+        };
+        walk(this.watchRoot);
+        return snapshot;
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.enqueue(async () => {
+                await this.processPendingFiles();
+            });
+        }, this.flushDebounceMs);
+    }
+    async processPendingFiles() {
+        if (this.pendingFiles.size === 0)
+            return;
+        const changedFiles = [...this.pendingFiles].sort();
+        this.pendingFiles.clear();
+        let affectedSystems = this.findAffectedSystems(changedFiles);
+        if (affectedSystems.length === 0) {
+            this.refreshSystems(true);
+            affectedSystems = this.findAffectedSystems(changedFiles);
+        }
+        if (affectedSystems.length === 0) {
+            this.log(`No living-doc systems matched ${changedFiles.length} changed paths`);
+            return;
+        }
+        this.log(`Compiling ${affectedSystems.length} local system(s) from ${changedFiles.length} file change(s)`);
+        for (const system of affectedSystems) {
+            await this.compileSystem(system, `${changedFiles.length} local file change${changedFiles.length === 1 ? '' : 's'}`, changedFiles);
+        }
+    }
+    findAffectedSystems(files) {
+        const matched = new Map();
+        for (const file of files) {
+            for (const system of this.systems) {
+                if (matchesDirectoryPath(file, system.directory_path)) {
+                    matched.set(system.system_id, system);
+                }
+            }
+        }
+        return [...matched.values()].sort((a, b) => a.directory_path.localeCompare(b.directory_path));
+    }
+    /**
+     * Pull server-compiled (Gemini Pro) docs from the platform registry.
+     * These are richer than local mechanical docs — narrative architecture,
+     * data flow, gotchas, connected systems, conventions.
+     *
+     * Only overwrites local docs that are locally-compiled (not server-compiled).
+     * Runs on every startup (fast — single API call, writes only changed files).
+     */
+    async syncServerCompiledDocs() {
+        if (!this.apiUrl || !this.apiKey)
+            return;
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 8000);
+            const systemIds = this.systems.map(s => s.system_id);
+            const res = await fetch(`${this.apiUrl}/api/v1/living-docs/compiled`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ system_ids: systemIds }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (!res.ok) {
+                this.log(`Server sync returned ${res.status} — skipping`);
+                return;
+            }
+            const data = await res.json();
+            if (!data.docs || data.docs.length === 0) {
+                this.log('No server-compiled docs available');
+                return;
+            }
+            let synced = 0;
+            for (const doc of data.docs) {
+                if (!doc.compiled_body || doc.compiled_body.length < 100)
+                    continue;
+                const systemRoot = doc.directory_path === '.' ? this.repoRoot : (0, path_1.join)(this.repoRoot, doc.directory_path);
+                const contextPath = (0, path_1.join)(systemRoot, 'ekkOS_CONTEXT.md');
+                // Only overwrite if local doc is locally-compiled (or doesn't exist)
+                if ((0, fs_1.existsSync)(contextPath)) {
+                    try {
+                        const existing = (0, fs_1.readFileSync)(contextPath, 'utf-8');
+                        const isServerCompiled = existing.includes('compiled_by: ekkOS Server Compiler')
+                            || existing.includes('compiler_model: gemini')
+                            || (existing.includes('compiled_by:') && !existing.includes('compiled_by: ekkOS Local Compiler'));
+                        // If already server-compiled, check if the new one is newer
+                        if (isServerCompiled) {
+                            const existingDate = existing.match(/last_compiled_at:\s*(.+)/)?.[1]?.trim();
+                            if (existingDate && new Date(existingDate) >= new Date(doc.compiled_at)) {
+                                continue; // Existing is same or newer
+                            }
+                        }
+                    }
+                    catch { /* overwrite on error */ }
+                }
+                try {
+                    (0, fs_1.writeFileSync)(contextPath, doc.compiled_body, 'utf-8');
+                    synced++;
+                }
+                catch (err) {
+                    this.log(`Failed to write server doc for ${doc.system_id}: ${err.message}`);
+                }
+            }
+            if (synced > 0) {
+                this.log(`Synced ${synced} server-compiled (Gemini) docs to disk`);
+            }
+        }
+        catch (err) {
+            // Non-fatal — server sync failure shouldn't block local compilation
+            const msg = err.message;
+            if (!msg.includes('aborted')) {
+                this.log(`Server sync failed: ${msg}`);
+            }
+        }
+    }
+    async compileStaleSystems(reason) {
+        for (const system of this.systems) {
+            await this.compileSystem(system, reason, []);
+        }
+    }
+    collectSystemFiles(system) {
+        const systemRoot = system.directory_path === '.' ? this.repoRoot : (0, path_1.join)(this.repoRoot, system.directory_path);
+        const files = [];
+        const walk = (dirPath) => {
+            let entries;
+            try {
+                entries = (0, fs_1.readdirSync)(dirPath);
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const fullPath = (0, path_1.join)(dirPath, entry);
+                let stats;
+                try {
+                    stats = (0, fs_1.statSync)(fullPath);
+                }
+                catch {
+                    continue;
+                }
+                if (stats.isDirectory()) {
+                    if (DEFAULT_EXCLUDED_DIRS.has(entry) || entry.startsWith('.'))
+                        continue;
+                    walk(fullPath);
+                    continue;
+                }
+                const relativePath = normalizePath((0, path_1.relative)(systemRoot, fullPath));
+                if (!isWatchableFile(relativePath))
+                    continue;
+                const ext = (0, path_1.extname)(entry).toLowerCase();
+                if (ext && !DEFAULT_SOURCE_EXTENSIONS.has(ext) && !DEFAULT_KEY_FILE_NAMES.includes(entry))
+                    continue;
+                let content = '';
+                try {
+                    content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                files.push({
+                    relativePath,
+                    fullPath,
+                    size: stats.size,
+                    ext,
+                    content,
+                    contentHash: sha256(content),
+                });
+            }
+        };
+        walk(systemRoot);
+        return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    }
+    async compileSystem(system, reason, changedFiles) {
+        const files = this.collectSystemFiles(system);
+        if (files.length === 0)
+            return;
+        const systemRoot = system.directory_path === '.' ? this.repoRoot : (0, path_1.join)(this.repoRoot, system.directory_path);
+        const fingerprint = sha256(files.map(file => `${file.relativePath}:${file.contentHash}`).join('\n'));
+        const contextPath = (0, path_1.join)(systemRoot, 'ekkOS_CONTEXT.md');
+        if ((0, fs_1.existsSync)(contextPath)) {
+            try {
+                const existing = (0, fs_1.readFileSync)(contextPath, 'utf-8');
+                // NEVER overwrite a server-compiled (Gemini) doc with the local mechanical template.
+                // Server docs are richer — they include narrative architecture, data flow, gotchas, etc.
+                // Instead: metadata-only patch (update frontmatter, preserve body).
+                const isServerCompiled = existing.includes('compiled_by: ekkOS Server Compiler')
+                    || existing.includes('compiler_model: gemini')
+                    || (existing.includes('compiled_by:') && !existing.includes('compiled_by: ekkOS Local Compiler'));
+                if (isServerCompiled) {
+                    // Phase 3: Metadata-only patching — update frontmatter fields without touching body
+                    this.patchServerDocMetadata(contextPath, existing, system, reason);
+                    return;
+                }
+                // Same fingerprint + same template version = nothing changed → skip
+                if (parseStoredFingerprint(existing) === fingerprint &&
+                    existing.includes('\ncompiled_timezone: ') &&
+                    parseStoredTemplateVersion(existing) === LOCAL_CONTEXT_TEMPLATE_VERSION) {
+                    return;
+                }
+            }
+            catch {
+                // Fall through and rewrite.
+            }
+        }
+        const extCounts = new Map();
+        for (const file of files) {
+            const ext = file.ext || '(none)';
+            extCounts.set(ext, (extCounts.get(ext) || 0) + 1);
+        }
+        const envVars = extractEnvVars(files.slice(0, 20).map(file => file.content));
+        // Detect stack for language-aware compilation
+        const fileList = files.map(f => f.relativePath);
+        const stack = await (0, stack_detection_js_1.detectStack)(fileList, async (path) => {
+            const f = files.find(x => x.relativePath === path);
+            return f?.content ?? null;
+        });
+        // Language-aware key files and entry points
+        const stackKeyFiles = new Set((0, language_config_js_1.getKeyFilesForStack)(stack).map(f => f.toLowerCase()));
+        const dependencies = extractDependencies((0, path_1.join)(systemRoot, 'package.json'));
+        const recentChanges = readRecentGitChanges(this.repoRoot, system.directory_path, this.timeZone);
+        const entryFileNames = ['index.ts', 'index.tsx', 'index.js', 'main.ts', 'server.ts', 'app.ts',
+            'main.py', 'app.py', 'manage.py', '__main__.py', 'main.rs', 'lib.rs', 'main.go', 'config.ru',
+            'Program.cs', 'lib/main.dart'];
+        const entryPoints = files.filter(file => entryFileNames.includes((0, path_1.basename)(file.relativePath)));
+        const readmeCount = files.filter(file => (0, path_1.basename)(file.relativePath).toLowerCase() === 'readme.md').length;
+        const testFileCount = files.filter(file => /(^|\/).*(test|spec)\.[^/]+$/i.test(file.relativePath)).length;
+        const packageManifestCount = files.filter(file => (0, path_1.basename)(file.relativePath) === 'package.json').length;
+        const directoryCount = new Set(files
+            .map(file => normalizePath(file.relativePath).split('/').slice(0, -1).join('/'))
+            .filter(Boolean)).size;
+        const now = formatZonedTimestamp(new Date(), this.timeZone);
+        const observedTimes = changedFiles
+            .map(file => {
+            try {
+                return (0, fs_1.statSync)((0, path_1.join)(this.repoRoot, file)).mtime.getTime();
+            }
+            catch {
+                return Date.now();
+            }
+        })
+            .filter(time => !Number.isNaN(time))
+            .sort((a, b) => a - b);
+        const evidenceStart = observedTimes.length > 0
+            ? formatZonedTimestamp(new Date(observedTimes[0]), this.timeZone)
+            : (recentChanges[recentChanges.length - 1]?.timestamp || now);
+        const evidenceEnd = observedTimes.length > 0
+            ? formatZonedTimestamp(new Date(observedTimes[observedTimes.length - 1]), this.timeZone)
+            : (recentChanges[0]?.timestamp || now);
+        const topExtensions = [...extCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 4)
+            .map(([ext, count]) => `${ext.replace(/^\./, '') || 'none'} (${count})`)
+            .join(', ');
+        // ── Dead code / activity detection ──────────────────────────────────────
+        const lastCommitEpochMs = (() => {
+            try {
+                const scope = system.directory_path === '.' ? '.' : system.directory_path;
+                // Exclude ekkOS_CONTEXT.md from the query so auto-generated writes don't mask staleness
+                const raw = (0, child_process_1.execSync)(`git -C ${JSON.stringify(this.repoRoot)} log --max-count=1 --pretty=format:%ct -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                return raw ? Number(raw) * 1000 : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        const daysSinceLastChange = lastCommitEpochMs
+            ? Math.floor((Date.now() - lastCommitEpochMs) / (1000 * 60 * 60 * 24))
+            : null;
+        const DORMANT_THRESHOLD_DAYS = 90;
+        const STALE_THRESHOLD_DAYS = 30;
+        let activityStatus = 'active';
+        if (daysSinceLastChange !== null) {
+            if (daysSinceLastChange >= DORMANT_THRESHOLD_DAYS)
+                activityStatus = 'dormant';
+            else if (daysSinceLastChange >= STALE_THRESHOLD_DAYS)
+                activityStatus = 'stale';
+        }
+        const bodySections = [];
+        const title = system.directory_path === '.' ? (0, path_1.basename)(this.repoRoot) : system.directory_path;
+        bodySections.push(`# ${title}`);
+        bodySections.push('');
+        // ── Health warnings ──
+        if (activityStatus === 'dormant') {
+            bodySections.push(`> **⚠️ POTENTIAL DEAD CODE** — No commits in ${daysSinceLastChange} days. Review whether this system is still needed.`);
+            bodySections.push('');
+        }
+        else if (activityStatus === 'stale') {
+            bodySections.push(`> **⏸ Inactive** — Last commit was ${daysSinceLastChange} days ago. May be stable or may need attention.`);
+            bodySections.push('');
+        }
+        // ── Purpose (from README first line or package.json description) ──
+        const purposeText = extractPurpose(files);
+        if (purposeText) {
+            bodySections.push(purposeText);
+            bodySections.push('');
+        }
+        // ── Architecture ──
+        bodySections.push('## Architecture');
+        const runtimeDesc = stack.language !== 'unknown'
+            ? `${stack.language}${stack.framework ? ` / ${stack.framework}` : ''}${stack.packageManager ? ` (${stack.packageManager})` : ''}`
+            : describeRuntime(extCounts);
+        bodySections.push(`- **Runtime**: ${runtimeDesc}`);
+        if (entryPoints.length > 0) {
+            bodySections.push(`- **Entry points**: ${entryPoints.map(f => `\`${(0, path_1.basename)(f.relativePath)}\``).join(', ')}`);
+        }
+        if (dependencies.length > 0) {
+            bodySections.push(`- **Key dependencies**: ${dependencies.map(dep => `\`${dep}\``).join(', ')}`);
+        }
+        bodySections.push(`- **Size**: ${files.length} files across ${directoryCount} directories (${topExtensions})`);
+        if (testFileCount > 0)
+            bodySections.push(`- **Tests**: ${testFileCount} test file(s)`);
+        bodySections.push('');
+        // ── Key Modules (top-level source files and directories) ──
+        const keyModules = extractKeyModules(files, system.directory_path);
+        if (keyModules.length > 0) {
+            bodySections.push('## Key Modules');
+            for (const mod of keyModules) {
+                bodySections.push(`- \`${mod.path}\` — ${mod.description}`);
+            }
+            bodySections.push('');
+        }
+        // ── Environment Variables ──
+        if (envVars.length > 0) {
+            bodySections.push('## Environment Variables');
+            for (const envVar of envVars) {
+                bodySections.push(`- \`${envVar}\``);
+            }
+            bodySections.push('');
+        }
+        // ── Change Log (rich history with files + why) ──
+        bodySections.push('## Change Log');
+        if (recentChanges.length === 0) {
+            bodySections.push('No recent git commits found for this directory.');
+        }
+        else {
+            for (const change of recentChanges) {
+                const readableDate = formatReadableDate(change.timestamp);
+                bodySections.push(`- **${readableDate}**: ${escapeInline(change.message)}`);
+            }
+        }
+        bodySections.push('');
+        // ── Active Work (what triggered this recompile) ──
+        if (changedFiles.length > 0) {
+            bodySections.push('## Active Work');
+            bodySections.push(`These ${changedFiles.length} file(s) changed since last compile:`);
+            bodySections.push('');
+            for (const file of changedFiles.slice(0, 15)) {
+                const shortFile = file.split('/').slice(-2).join('/');
+                bodySections.push(`- \`${shortFile}\``);
+            }
+            if (changedFiles.length > 15) {
+                bodySections.push(`- ... and ${changedFiles.length - 15} more`);
+            }
+            bodySections.push('');
+        }
+        // ── Metadata footer ──
+        bodySections.push('## System Info');
+        bodySections.push(`- **Path**: \`${system.directory_path}\` · **ID**: \`${system.system_id}\` · **Domain**: \`${system.domain}\``);
+        bodySections.push(`- **Status**: ${activityStatus}${daysSinceLastChange !== null ? ` (${daysSinceLastChange}d since last commit)` : ''} · **Compiled**: ${formatReadableDate(now)}`);
+        if (reason !== 'initial local compile') {
+            bodySections.push(`- **Trigger**: ${reason}`);
+        }
+        const assembledBody = bodySections.join('\n');
+        const contentHash = sha256(assembledBody);
+        const frontmatter = [
+            '---',
+            `system_id: ${system.system_id}`,
+            `domain: ${system.domain}`,
+            'status: active',
+            `last_compiled_at: ${now}`,
+            `compiled_timezone: ${this.timeZone}`,
+            `activity_status: ${activityStatus}`,
+            `days_since_last_change: ${daysSinceLastChange ?? 'unknown'}`,
+            `content_hash: ${contentHash}`,
+            `invalidation_fingerprint: ${fingerprint}`,
+            `recompile_reason: ${JSON.stringify(reason)}`,
+            'source_event_ids: []',
+            `source_event_count: ${changedFiles.length}`,
+            `evidence_window_start: ${evidenceStart}`,
+            `evidence_window_end: ${evidenceEnd}`,
+            'confidence: medium',
+            'redactions: 0',
+            'compiled_by: ekkOS Local Compiler',
+            'compiler_model: local-mechanical-v1',
+            `compiler_template_version: ${LOCAL_CONTEXT_TEMPLATE_VERSION}`,
+            '---',
+        ].join('\n');
+        const markdown = [
+            frontmatter,
+            '',
+            `<!-- EKKOS_AUTOGENERATED_START ${contentHash} -->`,
+            '',
+            assembledBody,
+            '',
+            '<!-- EKKOS_AUTOGENERATED_END -->',
+            '',
+            '---',
+            '*Generated directly from the local workspace to keep CLI context aligned with on-disk code.*',
+            '',
+        ].join('\n');
+        (0, fs_1.mkdirSync)(systemRoot, { recursive: true });
+        // Atomic write: temp file + rename to prevent corruption on crash
+        const tmpPath = (0, path_1.join)((0, path_1.dirname)(contextPath), `.ekkOS_CONTEXT.md.${process.pid}.tmp`);
+        (0, fs_1.writeFileSync)(tmpPath, markdown, 'utf-8');
+        (0, fs_1.renameSync)(tmpPath, contextPath);
+        this.log(`Wrote ${normalizePath((0, path_1.relative)(this.repoRoot, contextPath))}${stack.language !== 'unknown' ? ` [${stack.language}${stack.framework ? `/${stack.framework}` : ''}]` : ''}`);
+    }
+    /**
+     * Metadata-only patch for server-compiled docs.
+     * Updates ONLY the approved local-mutable frontmatter fields without touching the body.
+     * Fields: activity_status, days_since_last_change, last_compiled_at, compiled_timezone, recompile_reason
+     */
+    patchServerDocMetadata(contextPath, existing, system, reason) {
+        try {
+            const lastCommitEpochMs = (() => {
+                try {
+                    const scope = system.directory_path === '.' ? '.' : system.directory_path;
+                    const raw = (0, child_process_1.execSync)(`git -C ${JSON.stringify(this.repoRoot)} log --max-count=1 --pretty=format:%ct -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                    return raw ? Number(raw) * 1000 : null;
+                }
+                catch {
+                    return null;
+                }
+            })();
+            const daysSinceLastChange = lastCommitEpochMs
+                ? Math.floor((Date.now() - lastCommitEpochMs) / (1000 * 60 * 60 * 24))
+                : null;
+            let activityStatus = 'active';
+            if (daysSinceLastChange !== null) {
+                if (daysSinceLastChange >= 90)
+                    activityStatus = 'dormant';
+                else if (daysSinceLastChange >= 30)
+                    activityStatus = 'stale';
+            }
+            const now = formatZonedTimestamp(new Date(), this.timeZone);
+            // Patch only approved fields in frontmatter, preserve body byte-for-byte
+            const firstDash = existing.indexOf('---');
+            const frontmatterEnd = existing.indexOf('---', firstDash + 3);
+            if (frontmatterEnd === -1)
+                return;
+            const frontmatter = existing.slice(0, frontmatterEnd + 3);
+            const body = existing.slice(frontmatterEnd + 3);
+            // Detect and preserve line ending style (LF vs CRLF)
+            const lineEnding = existing.includes('\r\n') ? '\r\n' : '\n';
+            const patches = [
+                [/^activity_status: .+$/m, `activity_status: ${activityStatus}`],
+                [/^days_since_last_change: .+$/m, `days_since_last_change: ${daysSinceLastChange ?? 'unknown'}`],
+                [/^last_compiled_at: .+$/m, `last_compiled_at: ${now}`],
+                [/^compiled_timezone: .+$/m, `compiled_timezone: ${this.timeZone}`],
+                [/^recompile_reason: .+$/m, `recompile_reason: ${JSON.stringify(reason)}`],
+            ];
+            let patched = frontmatter;
+            let patchCount = 0;
+            for (const [regex, replacement] of patches) {
+                if (regex.test(patched)) {
+                    patched = patched.replace(regex, replacement);
+                    patchCount++;
+                }
+            }
+            if (patchCount === 0) {
+                this.log(`Skipping ${system.directory_path} — server doc (no patchable fields)`);
+                return;
+            }
+            const result = patched + body;
+            const finalResult = lineEnding === '\r\n' ? result.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n') : result;
+            // Atomic write
+            const tmpPath = (0, path_1.join)((0, path_1.dirname)(contextPath), `.ekkOS_CONTEXT.md.${process.pid}.tmp`);
+            (0, fs_1.writeFileSync)(tmpPath, finalResult, 'utf-8');
+            (0, fs_1.renameSync)(tmpPath, contextPath);
+            this.log(`Patched metadata for ${system.directory_path} (${activityStatus}, ${daysSinceLastChange}d) — server body preserved`);
+        }
+        catch (err) {
+            this.log(`Metadata patch failed for ${system.directory_path}: ${err.message}`);
+        }
+    }
+}
+exports.LocalLivingDocsManager = LocalLivingDocsManager;