@letterblack/lbe-core 1.3.4 → 1.3.6

package/src/state/fileIndex.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const FORMAT = 1;
+
+// Directories always excluded from indexing
+const IGNORE_DIRS = new Set([
+    '.git', 'node_modules', 'dist', 'coverage', '.lbe',
+]);
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Computes the SHA-256 hash of a file's contents.
+ *
+ * @param {string} filePath  Absolute path to the file.
+ * @returns {string}         Hex digest.
+ */
+export function hashFile(filePath) {
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Recursively walks a directory, yielding relative posix paths and stats.
+ * Skips IGNORE_DIRS entries and any symlinks.
+ */
+function* walk(root, rel = '') {
+    const entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isSymbolicLink()) continue;
+        const entryRel = rel ? rel + '/' + entry.name : entry.name;
+        if (entry.isDirectory()) {
+            if (IGNORE_DIRS.has(entry.name)) continue;
+            yield* walk(root, entryRel);
+        } else if (entry.isFile()) {
+            yield entryRel;
+        }
+    }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Indexes all files under workspaceRoot and writes the result to outputPath.
+ *
+ * @param {string} workspaceRoot  Absolute workspace root to index.
+ * @param {string} outputPath     Where to write the JSON index file.
+ * @param {object} [opts]         Reserved for future use.
+ * @returns {object}              The index object that was written.
+ */
+export function indexFiles(workspaceRoot, outputPath, _opts = {}) {
+    if (!workspaceRoot || typeof workspaceRoot !== 'string') {
+        throw new TypeError('workspaceRoot must be a non-empty string');
+    }
+    if (!outputPath || typeof outputPath !== 'string') {
+        throw new TypeError('outputPath must be a non-empty string');
+    }
+
+    const absRoot    = path.resolve(workspaceRoot);
+    const absOutput  = path.resolve(outputPath);
+    const outputNorm = absOutput.replace(/\\/g, '/');
+    const rootNorm   = absRoot.replace(/\\/g, '/');
+
+    // Reject output paths inside the indexed tree — the output file itself
+    // would be included in the next index, creating a self-referential loop.
+    if (outputNorm.startsWith(rootNorm + '/') || outputNorm === rootNorm) {
+        // Allow if output is under an ignored directory (e.g. .lbe/)
+        const relOutput = path.relative(absRoot, absOutput).replace(/\\/g, '/');
+        const firstSeg  = relOutput.split('/')[0];
+        if (!IGNORE_DIRS.has(firstSeg)) {
+            throw new Error(
+                `outputPath "${outputPath}" is inside the indexed tree. ` +
+                'Place the output in an excluded directory (e.g. .lbe/) or outside the root.'
+            );
+        }
+    }
+
+    const files = {};
+    for (const relPath of walk(absRoot)) {
+        const absPath = path.join(absRoot, relPath);
+        const stat    = fs.statSync(absPath);
+        files[relPath] = {
+            sha256:  hashFile(absPath),
+            size:    stat.size,
+            mtimeMs: stat.mtimeMs,
+        };
+    }
+
+    const index = {
+        format:    FORMAT,
+        ts:        new Date().toISOString(),
+        workspace: absRoot.replace(/\\/g, '/'),
+        files,
+    };
+
+    const outDir = path.dirname(absOutput);
+    if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(absOutput, JSON.stringify(index, null, 2) + '\n', 'utf8');
+    return index;
+}
+
+/**
+ * Computes the diff between two file index snapshots.
+ *
+ * @param {string} beforePath  Path to the before JSON index.
+ * @param {string} afterPath   Path to the after JSON index.
+ * @returns {object}           { added, removed, changed, unchanged }
+ */
+export function diffIndex(beforePath, afterPath) {
+    function loadIndex(p) {
+        if (!p || !fs.existsSync(p)) return { files: {} };
+        try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+        catch (_) { return { files: {} }; }
+    }
+
+    const before = loadIndex(beforePath);
+    const after  = loadIndex(afterPath);
+
+    const beforeFiles = before.files || {};
+    const afterFiles  = after.files  || {};
+
+    const added    = [];
+    const removed  = [];
+    const changed  = [];
+    const unchanged = [];
+
+    const allKeys = new Set([...Object.keys(beforeFiles), ...Object.keys(afterFiles)]);
+    for (const k of allKeys) {
+        const b = beforeFiles[k];
+        const a = afterFiles[k];
+        if (!b)                        { added.push(k); }
+        else if (!a)                   { removed.push(k); }
+        else if (b.sha256 !== a.sha256){ changed.push(k); }
+        else                           { unchanged.push(k); }
+    }
+
+    return { added, removed, changed, unchanged };
+}

package/src/state/index.cjs

@@ -0,0 +1,101 @@
+'use strict';
+// CJS mirror of src/state/index.js — minimal subset for register.cjs preload use.
+//
+// ESM modules cannot be require()'d synchronously. This file duplicates the
+// pure path-computation functions inline so register.cjs has no ESM dependency.
+//
+// Rule: this file must remain pure CJS. No import(), no top-level await.
+// Policy authority: .lbe/policy.json remains authoritative. This file resolves
+// central state paths only — it does not read or write policy.
+
+const fs     = require('fs');
+const path   = require('path');
+const os     = require('os');
+const crypto = require('crypto');
+
+// ── Inline mirrors of ESM functions (pure, no side effects) ─────────────────
+
+function canonicalWorkspacePath(workspaceRoot) {
+    var resolved;
+    try {
+        resolved = fs.realpathSync.native(workspaceRoot);
+    } catch (_) {
+        resolved = path.resolve(workspaceRoot);
+    }
+    var normalised = path.normalize(resolved);
+    return process.platform === 'win32' ? normalised.toLowerCase() : normalised;
+}
+
+function workspaceId(workspaceRoot) {
+    return crypto.createHash('sha256').update(canonicalWorkspacePath(workspaceRoot)).digest('hex');
+}
+
+function stateRoot() {
+    var home = os.homedir();
+
+    if (process.platform === 'win32') {
+        var localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+        return path.join(localAppData, 'LetterBlack', 'Sentinel');
+    }
+
+    if (process.platform === 'darwin') {
+        var appSupport = process.env.HOME
+            ? path.join(process.env.HOME, 'Library', 'Application Support')
+            : path.join(home, 'Library', 'Application Support');
+        return path.join(appSupport, 'LetterBlack', 'Sentinel');
+    }
+
+    // Linux / other POSIX
+    var xdgData = process.env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+    return path.join(xdgData, 'LetterBlack', 'Sentinel');
+}
+
+function workspaceStateDir(root, id) {
+    return path.join(root, 'workspaces', id.slice(0, 2), id.slice(2, 4), id.slice(4, 6), id);
+}
+
+function buildPaths(dir) {
+    return {
+        workspace:       path.join(dir, 'workspace.json'),
+        events:          path.join(dir, 'lbe-events.jsonl'),
+        intent:          path.join(dir, 'intent.jsonl'),
+        targetRegistry:  path.join(dir, 'target_registry.jsonl'),
+        fileIndexDir:    path.join(dir, 'file-index'),
+        fileIndexBefore: path.join(dir, 'file-index', 'before.json'),
+        fileIndexAfter:  path.join(dir, 'file-index', 'after.json'),
+        proofDir:        path.join(dir, 'proof'),
+        proofLatest:     path.join(dir, 'proof', 'latest.json'),
+    };
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Resolves (and creates) the central state directory for a workspace.
+ * Safe to call at preload time — only mkdirSync, no registry or audit writes.
+ *
+ * @param {string} workspaceRoot  Absolute path to the workspace root.
+ * @returns {{ stateDir: string, workspaceId: string, paths: object }}
+ */
+function resolveWorkspaceStateSyncCjs(workspaceRoot) {
+    var root = stateRoot();
+    var id   = workspaceId(workspaceRoot);
+    var dir  = workspaceStateDir(root, id);
+
+    fs.mkdirSync(dir,                           { recursive: true });
+    fs.mkdirSync(path.join(dir, 'file-index'), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'proof'),      { recursive: true });
+
+    return {
+        stateDir:    dir,
+        workspaceId: id,
+        paths:       buildPaths(dir),
+    };
+}
+
+module.exports = {
+    resolveWorkspaceStateSyncCjs,
+    stateRoot,
+    workspaceId,
+    workspaceStateDir,
+};

package/src/state/index.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { workspaceId, workspaceStateDir } from './workspaceId.js';
+import { stateRoot } from './stateRoot.js';
+import { registerWorkspace } from './workspaceRegistry.js';
+import { migrateLegacyEvents } from './migration.js';
+
+export { workspaceId, workspaceStateDir, stateRoot };
+
+/**
+ * Resolves (and creates) the central state directory for a workspace.
+ *
+ * Returned paths object is the contract for all subsequent state operations.
+ * The ESM resolver also refreshes the central workspace registry. The hook CJS
+ * resolver remains separate and deliberately does not perform this write.
+ *
+ * Safe to call multiple times — mkdirSync with recursive:true is idempotent.
+ *
+ * @param {string} workspaceRoot  Absolute path to the workspace root.
+ * @returns {{ stateDir: string, workspaceId: string, paths: WorkspacePaths }}
+ */
+export function resolveWorkspaceState(workspaceRoot) {
+    const root = stateRoot();
+    const id   = workspaceId(workspaceRoot);
+    const dir  = workspaceStateDir(root, id);
+
+    // Ensure directory tree exists — idempotent.
+    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(path.join(dir, 'file-index'), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'proof'),      { recursive: true });
+    registerWorkspace(path.join(root, 'registry.json'), id, workspaceRoot);
+    migrateLegacyEvents(workspaceRoot, dir);
+
+    return {
+        stateDir:    dir,
+        workspaceId: id,
+        paths:       buildPaths(dir),
+    };
+}
+
+/**
+ * @typedef {Object} WorkspacePaths
+ * @property {string} workspace      workspace.json
+ * @property {string} events         lbe-events.jsonl  (central audit mirror)
+ * @property {string} intent         intent.jsonl
+ * @property {string} targetRegistry target_registry.jsonl
+ * @property {string} fileIndexDir   file-index/
+ * @property {string} fileIndexBefore file-index/before.json
+ * @property {string} fileIndexAfter  file-index/after.json
+ * @property {string} proofDir       proof/
+ * @property {string} proofLatest    proof/latest.json
+ */
+function buildPaths(dir) {
+    return {
+        workspace:        path.join(dir, 'workspace.json'),
+        events:           path.join(dir, 'lbe-events.jsonl'),
+        intent:           path.join(dir, 'intent.jsonl'),
+        targetRegistry:   path.join(dir, 'target_registry.jsonl'),
+        fileIndexDir:     path.join(dir, 'file-index'),
+        fileIndexBefore:  path.join(dir, 'file-index', 'before.json'),
+        fileIndexAfter:   path.join(dir, 'file-index', 'after.json'),
+        proofDir:         path.join(dir, 'proof'),
+        proofLatest:      path.join(dir, 'proof', 'latest.json'),
+    };
+}

package/src/state/intentRegistry.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const INTENT_FILE = 'intent.jsonl';
+
+// ── Validation ────────────────────────────────────────────────────────────────
+
+function validateFilePaths(paths, fieldName) {
+    if (!Array.isArray(paths)) return;
+    for (const p of paths) {
+        if (typeof p !== 'string') continue;
+        const normalized = p.replace(/\\/g, '/');
+        const isAbsolute = path.isAbsolute(p) || path.win32.isAbsolute(p) || path.win32.isAbsolute(normalized);
+        if (isAbsolute) {
+            throw new Error(`${fieldName}: absolute paths are not allowed: "${p}"`);
+        }
+        if (normalized.split('/').some(seg => seg === '..')) {
+            throw new Error(`${fieldName}: ../ traversal is not allowed: "${p}"`);
+        }
+    }
+}
+
+function normalizeFilePaths(paths) {
+    if (!Array.isArray(paths)) return paths;
+    return paths.map(p => (typeof p === 'string' ? p.replace(/\\/g, '/') : p));
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Registers an intent record, appending it to stateDir/intent.jsonl.
+ *
+ * @param {string} stateDir  Central workspace state directory.
+ * @param {object} intent    Intent record (task, reason, allowed_files, …).
+ * @returns {object}         The stored record (with generated intent_id and ts).
+ */
+export function registerIntent(stateDir, intent) {
+    if (!stateDir || typeof stateDir !== 'string') {
+        throw new TypeError('stateDir must be a non-empty string');
+    }
+    if (!intent || typeof intent !== 'object') {
+        throw new TypeError('intent must be a plain object');
+    }
+
+    validateFilePaths(intent.allowed_files,   'allowed_files');
+    validateFilePaths(intent.forbidden_files, 'forbidden_files');
+
+    const record = {
+        intent_id:        intent.intent_id || ('i_' + crypto.randomBytes(8).toString('hex')),
+        ts:               intent.ts        || new Date().toISOString(),
+        task:             intent.task              ?? '',
+        reason:           intent.reason            ?? '',
+        allowed_files:    normalizeFilePaths(intent.allowed_files    ?? []),
+        forbidden_files:  normalizeFilePaths(intent.forbidden_files  ?? []),
+        declared_targets: intent.declared_targets  ?? [],
+        risk:             intent.risk              ?? 'unknown',
+    };
+
+    const filePath = path.join(stateDir, INTENT_FILE);
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    fs.appendFileSync(filePath, JSON.stringify(record) + '\n', 'utf8');
+    return record;
+}
+
+/**
+ * Loads all intent records from stateDir/intent.jsonl.
+ * Malformed lines are silently skipped.
+ *
+ * @param {string} stateDir  Central workspace state directory.
+ * @returns {object[]}       Array of parsed intent records (may be empty).
+ */
+export function loadIntents(stateDir) {
+    const filePath = path.join(stateDir, INTENT_FILE);
+    if (!fs.existsSync(filePath)) return [];
+    const raw = fs.readFileSync(filePath, 'utf8').trim();
+    if (!raw) return [];
+    return raw.split('\n').reduce((acc, line) => {
+        try { acc.push(JSON.parse(line)); } catch (_) { /* ignore */ }
+        return acc;
+    }, []);
+}

package/src/state/migration.js

@@ -0,0 +1,112 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicAppendFileSync, atomicWriteFileSync, withFileLock } from '../core/atomicWrite.js';
+
+const SOURCE = '.lbe/events.jsonl';
+
+function sha256(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+function readMarker(markerPath) {
+    try {
+        return JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    } catch (_) {
+        return null;
+    }
+}
+
+function readCentralLines(eventsPath) {
+    try {
+        return new Set(fs.readFileSync(eventsPath, 'utf8').split(/\r?\n/).filter(Boolean));
+    } catch (_) {
+        return new Set();
+    }
+}
+
+/**
+ * Imports a legacy project-local event log into the central log once per source
+ * content hash. The legacy source is read-only throughout this process.
+ */
+export function migrateLegacyEvents(workspaceRoot, stateDir) {
+    const sourcePath = path.join(workspaceRoot, '.lbe', 'events.jsonl');
+    const migrationDir = path.join(stateDir, 'migration');
+    const markerPath = path.join(migrationDir, 'events-v1.json');
+    const invalidPath = path.join(migrationDir, 'migration-invalid.jsonl');
+    const result = {
+        attempted: false,
+        imported_count: 0,
+        skipped_duplicate_count: 0,
+        invalid_count: 0,
+        markerPath,
+        invalidPath,
+    };
+
+    let source;
+    try {
+        if (!fs.existsSync(sourcePath)) return result;
+        source = fs.readFileSync(sourcePath, 'utf8');
+    } catch (_) {
+        return result;
+    }
+
+    result.attempted = true;
+    const sourceSha256 = sha256(source);
+    const marker = readMarker(markerPath);
+    if (marker?.format === 1 && marker.source_sha256 === sourceSha256) return result;
+
+    const validLines = [];
+    const invalidLines = [];
+    for (const [index, rawLine] of source.split(/\r?\n/).entries()) {
+        const line = rawLine.trim();
+        if (!line) continue;
+        try {
+            JSON.parse(line);
+            validLines.push(line);
+        } catch (_) {
+            invalidLines.push({ source: SOURCE, line_number: index + 1, line, source_sha256: sourceSha256 });
+        }
+    }
+
+    const eventsPath = path.join(stateDir, 'lbe-events.jsonl');
+    try {
+        withFileLock(eventsPath, () => {
+            const centralLines = readCentralLines(eventsPath);
+            const imported = [];
+            for (const line of validLines) {
+                if (centralLines.has(line)) {
+                    result.skipped_duplicate_count++;
+                    continue;
+                }
+                centralLines.add(line);
+                imported.push(line);
+                result.imported_count++;
+            }
+            if (imported.length > 0) {
+                const existing = fs.existsSync(eventsPath) ? fs.readFileSync(eventsPath, 'utf8') : '';
+                atomicWriteFileSync(eventsPath, existing + (existing && !existing.endsWith('\n') ? '\n' : '') + imported.join('\n') + '\n', 'utf8');
+            }
+        });
+
+        if (invalidLines.length > 0) {
+            atomicAppendFileSync(invalidPath, invalidLines.map(line => JSON.stringify(line) + '\n').join(''), { encoding: 'utf8' });
+            result.invalid_count = invalidLines.length;
+        }
+
+        fs.mkdirSync(migrationDir, { recursive: true });
+        atomicWriteFileSync(markerPath, JSON.stringify({
+            format: 1,
+            source: SOURCE,
+            source_sha256: sourceSha256,
+            migrated_at: new Date().toISOString(),
+            imported_count: result.imported_count,
+            skipped_duplicate_count: result.skipped_duplicate_count,
+            invalid_count: result.invalid_count,
+        }, null, 2) + '\n', 'utf8');
+    } catch (_) {
+        // Central-state migration is opportunistic; resolution must remain safe.
+    }
+
+    return result;
+}