@letterblack/lbe-core 1.3.4 → 1.3.5

package/src/cli/commands/dryrun.js

@@ -0,0 +1,175 @@
+// src/cli/commands/dryrun.js
+// Validate proposal and simulate execution
+
+import fs from 'fs';
+import path from 'path';
+import { validateCommand } from '../../core/validator.js';
+import { NonceStore } from '../../core/nonceStore.js';
+import { executeAdapter } from '../../adapters/index.js';
+import { loadKeysStore } from '../../core/trustedKeys.js';
+import { verifyPolicySignature } from '../../core/policySignature.js';
+import { validateAndUpdatePolicyVersionState } from '../../core/policyVersionGuard.js';
+
+export async function dryrunCommand(opts) {
+    const { in: inFile } = opts;
+    const config = opts.config || opts.policy;
+    const pubKey = opts['pub-key'];
+    const keysStorePath = opts['keys-store'] || path.resolve('.lbe/config/keys.json');
+    const policySigPath = opts['policy-sig'] || path.resolve('.lbe/config/policy.sig.json');
+    const policyStatePath = opts['policy-state'] || path.resolve('.lbe/data/policy.state.json');
+    const allowUnsignedPolicy = opts['policy-unsigned-ok'] === true || String(opts['policy-unsigned-ok']).toLowerCase() === 'true';
+    // Validate required arguments
+    if (!inFile) {
+        console.error('Error: --in <file> is required');
+        process.exit(1);
+    }
+
+    // Read proposal file
+    let proposal;
+    try {
+        const filePath = path.resolve(inFile);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        proposal = JSON.parse(content);
+    } catch (error) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'INVALID_PROPOSAL_FILE',
+            message: error.message
+        }));
+        process.exit(5);
+    }
+
+    // Load policy
+    let policy;
+    try {
+        const policyPath = config || path.resolve('.lbe/config/policy.default.json');
+        if (!fs.existsSync(policyPath)) {
+            console.error(JSON.stringify({
+                status: 'error',
+                error: 'MISSING_POLICY',
+                message: `Policy file not found: ${policyPath}`
+            }));
+            process.exit(1);
+        }
+        const policyContent = fs.readFileSync(policyPath, 'utf-8');
+        policy = JSON.parse(policyContent);
+    } catch (error) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'INVALID_POLICY',
+            message: error.message
+        }));
+        process.exit(1);
+    }
+
+    // Load key store (preferred) with legacy pub-key fallback
+    const keyStoreResult = loadKeysStore(keysStorePath);
+    const keyStore = keyStoreResult.ok ? keyStoreResult.store : null;
+
+    // Preflight: policy signature verification (strict by default)
+    const policySigCheck = verifyPolicySignature({
+        policyObj: policy,
+        keyStore,
+        policySigPath,
+        allowUnsigned: allowUnsignedPolicy
+    });
+    if (!policySigCheck.ok) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: policySigCheck.reason,
+            message: policySigCheck.message
+        }, null, 2));
+        process.exit(8);
+    }
+
+    const versionCheck = validateAndUpdatePolicyVersionState({
+        policyObj: policy,
+        statePath: policyStatePath,
+        maxCreatedAtSkewSec: policy?.security?.maxPolicyCreatedAtSkewSec
+    });
+    if (!versionCheck.ok) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: versionCheck.reason,
+            message: versionCheck.message
+        }, null, 2));
+        process.exit(8);
+    }
+
+    // Load nonce store
+    const nonceDb = new NonceStore(path.resolve('.lbe/data/nonce.db.json'));
+    await nonceDb.load();
+
+    if (!keyStore && !pubKey) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: 'MISSING_KEY_MATERIAL',
+            message: `${keyStoreResult.message}. Provide --pub-key/--pub-key-file or create .lbe/config/keys.json`
+        }));
+        process.exit(1);
+    }
+
+    // Validate command
+    const validateResult = validateCommand({
+        commandObj: proposal,
+        pubKeyB64: pubKey,
+        keyStore,
+        nonceDb,
+        policy
+    });
+
+    if (!validateResult.valid) {
+        const output = {
+            status: 'invalid',
+            commandId: proposal.commandId || 'N/A',
+            checks: validateResult.checks,
+            errors: validateResult.errors || [],
+            executionResult: null
+        };
+        console.log(JSON.stringify(output, null, 2));
+
+        if (validateResult.checks.schema === false) process.exit(5);
+        if (validateResult.checks.signature === false) process.exit(3);
+        if (validateResult.checks.nonce === false) process.exit(4);
+        if (validateResult.checks.timestamp === false) process.exit(6);
+        if (validateResult.checks.rateLimit === false) process.exit(7);
+        if (validateResult.checks.policy === false) process.exit(2);
+        process.exit(9);
+    }
+
+    // Simulate execution with noop adapter
+    let executionResult;
+    try {
+        const requesterPolicy = policy.requesters?.[proposal.requesterId];
+        executionResult = await executeAdapter(
+            'noop',
+            proposal,
+            policy,
+            requesterPolicy
+        );
+    } catch (error) {
+        executionResult = {
+            adapter: 'noop',
+            status: 'error',
+            error: error.message
+        };
+    }
+
+    // Output structured result
+    const output = {
+        status: 'valid_simulated',
+        commandId: proposal.commandId || 'N/A',
+        checks: validateResult.checks,
+        risk: validateResult.risk || 'UNKNOWN',
+        executionResult: {
+            adapter: executionResult.adapter,
+            status: executionResult.status,
+            output: executionResult.output || executionResult.error || '',
+            exitCode: executionResult.exitCode || 0,
+            note: 'This is a simulation using noop adapter. No actual execution occurred.'
+        }
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(0);
+}

package/src/cli/commands/health.js

@@ -0,0 +1,153 @@
+// src/cli/commands/health.js
+// Deployment health check command
+
+import fs from 'fs';
+import path from 'path';
+import { performIntegrityCheck } from '../../core/integrity.js';
+
+function toBoolean(value, defaultValue) {
+    if (value === undefined) return defaultValue;
+    if (value === true || value === false) return value;
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes') return true;
+    if (normalized === 'false' || normalized === '0' || normalized === 'no') return false;
+    return defaultValue;
+}
+
+function addCheck(checks, name, ok, message) {
+    checks[name] = { ok, message };
+}
+
+function canReadFile(filePath) {
+    try {
+        fs.accessSync(filePath, fs.constants.R_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function checkDataWritable(dataDir) {
+    const marker = path.join(dataDir, `.healthcheck-${Date.now()}`);
+    try {
+        fs.mkdirSync(dataDir, { recursive: true });
+        fs.writeFileSync(marker, 'ok', 'utf8');
+        fs.unlinkSync(marker);
+        return { ok: true, message: 'Data directory writable' };
+    } catch (error) {
+        return { ok: false, message: `Data directory not writable: ${error.message}` };
+    }
+}
+
+export async function healthCommand(opts) {
+    const jsonOutput = toBoolean(opts.json, true);
+    const policyPath = path.resolve(opts.config || opts.policy || '.lbe/config/policy.default.json');
+    const policySigPath = path.resolve(opts['policy-sig'] || '.lbe/config/policy.sig.json');
+    const keysStorePath = path.resolve(opts['keys-store'] || '.lbe/config/keys.json');
+    const dataDir = path.resolve(opts['data-dir'] || '.lbe/data');
+    const auditPath = path.resolve(opts.audit || path.join(dataDir, 'audit.log.jsonl'));
+    const noncePath = path.resolve(opts['nonce-db'] || path.join(dataDir, 'nonce.db.json'));
+    const ratePath = path.resolve(opts['rate-db'] || path.join(dataDir, 'rate-limit.db.json'));
+    const policyStatePath = path.resolve(opts['policy-state'] || path.join(dataDir, 'policy.state.json'));
+    const integrityStrict = toBoolean(opts['integrity-strict'], false);
+    const integrityManifestPath = path.resolve(opts['integrity-manifest'] || '.lbe/config/integrity.manifest.json');
+
+    const checks = {};
+
+    addCheck(
+        checks,
+        'policy',
+        fs.existsSync(policyPath) && canReadFile(policyPath),
+        fs.existsSync(policyPath)
+            ? `Policy file readable: ${policyPath}`
+            : `Policy file missing: ${policyPath}`
+    );
+
+    addCheck(
+        checks,
+        'policySignature',
+        fs.existsSync(policySigPath) && canReadFile(policySigPath),
+        fs.existsSync(policySigPath)
+            ? `Policy signature readable: ${policySigPath}`
+            : `Policy signature missing: ${policySigPath}`
+    );
+
+    addCheck(
+        checks,
+        'trustedKeys',
+        fs.existsSync(keysStorePath) && canReadFile(keysStorePath),
+        fs.existsSync(keysStorePath)
+            ? `Trusted keys readable: ${keysStorePath}`
+            : `Trusted keys missing: ${keysStorePath}`
+    );
+
+    addCheck(
+        checks,
+        'auditLog',
+        fs.existsSync(auditPath) && canReadFile(auditPath),
+        fs.existsSync(auditPath)
+            ? `Audit log readable: ${auditPath}`
+            : `Audit log missing: ${auditPath}`
+    );
+
+    addCheck(
+        checks,
+        'nonceDb',
+        fs.existsSync(noncePath) && canReadFile(noncePath),
+        fs.existsSync(noncePath)
+            ? `Nonce DB readable: ${noncePath}`
+            : `Nonce DB missing: ${noncePath}`
+    );
+
+    addCheck(
+        checks,
+        'rateLimitDb',
+        fs.existsSync(ratePath) && canReadFile(ratePath),
+        fs.existsSync(ratePath)
+            ? `Rate-limit DB readable: ${ratePath}`
+            : `Rate-limit DB missing: ${ratePath}`
+    );
+
+    addCheck(
+        checks,
+        'policyState',
+        fs.existsSync(policyStatePath) && canReadFile(policyStatePath),
+        fs.existsSync(policyStatePath)
+            ? `Policy state readable: ${policyStatePath}`
+            : `Policy state missing: ${policyStatePath}`
+    );
+
+    const writable = checkDataWritable(dataDir);
+    addCheck(checks, 'dataWritable', writable.ok, writable.message);
+
+    if (integrityStrict) {
+        const integrity = await performIntegrityCheck({
+            strict: true,
+            manifestPath: integrityManifestPath
+        });
+        addCheck(
+            checks,
+            'integrity',
+            integrity.valid,
+            integrity.valid
+                ? integrity.message
+                : `${integrity.reason}: ${integrity.message}`
+        );
+    }
+
+    const allOk = Object.values(checks).every((c) => c.ok === true);
+    const output = {
+        ok: allOk,
+        status: allOk ? 'healthy' : 'unhealthy',
+        timestamp: new Date().toISOString(),
+        checks
+    };
+
+    if (jsonOutput) {
+        console.log(JSON.stringify(output, null, 2));
+    } else {
+        console.log(`${output.status.toUpperCase()}: ${Object.keys(checks).length} checks`);
+    }
+
+    process.exit(allOk ? 0 : 8);
+}

package/src/cli/commands/init.js

@@ -0,0 +1,306 @@
+// src/cli/commands/init.js
+// Initialize LBE in a workspace:
+//   1. Scan project → generate workspace contract (semantics + enforcement)
+//   2. Show compact summary → ask once
+//   3. Write lbe.workspace.json
+//   4. Set up crypto infrastructure silently
+
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { generateKeyPair } from '../../core/signature.js';
+import { createPolicySignatureEnvelope } from '../../core/policySignature.js';
+import { scanWorkspace, formatSummary } from '../../core/workspaceScanner.js';
+
+// ─── Interactive prompt ───────────────────────────────────────────────────────
+
+function ask(question) {
+    // Non-interactive (CI / pipe) — default accept
+    if (!process.stdin.isTTY) return Promise.resolve('y');
+    return new Promise(resolve => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, ans => { rl.close(); resolve(ans.trim().toLowerCase()); });
+    });
+}
+
+// ─── Strict / relaxed adjustments ────────────────────────────────────────────
+
+function applyStrict(enforcement) {
+    // Strict: move approval items to deny, add common risky patterns
+    return {
+        ...enforcement,
+        deny: [...new Set([...enforcement.deny, ...enforcement.approval, '*.json', 'config/**'])],
+        approval: [],
+    };
+}
+
+function applyRelaxed(enforcement) {
+    // Relaxed: drop approval requirement, everything not denied is allowed
+    return { ...enforcement, approval: [] };
+}
+
+// ─── Crypto setup (silent — infrastructure only) ──────────────────────────────
+
+function setupCrypto(cwd) {
+    const nowIso      = new Date().toISOString();
+    const expiresAt   = new Date(Date.now() + 180 * 24 * 60 * 60 * 1000).toISOString();
+    const defaultKeyId = 'agent:gpt-v1-2026Q1';
+    const signerKeyId  = 'policy-signer-v1-2026Q1';
+
+    // All LBE infrastructure lives under .lbe/ — nothing pollutes the project root
+    const lbeDir = path.join(cwd, '.lbe');
+    for (const d of ['config', 'keys', 'data']) {
+        fs.mkdirSync(path.join(lbeDir, d), { recursive: true });
+    }
+
+    // Data stores
+    const dataFiles = {
+        '.lbe/data/nonce.db.json':      JSON.stringify({ entries: [] }, null, 2),
+        '.lbe/data/rate-limit.db.json': JSON.stringify({ entries: [] }, null, 2),
+        '.lbe/data/policy.state.json':  JSON.stringify({ schemaVersion: '1', lastAccepted: null, updatedAt: null }, null, 2),
+        '.lbe/data/audit.log.jsonl':    '',
+    };
+    for (const [rel, content] of Object.entries(dataFiles)) {
+        const p = path.join(cwd, rel);
+        if (!fs.existsSync(p)) fs.writeFileSync(p, content);
+    }
+
+    // Keypair
+    const keyDir    = path.join(lbeDir, 'keys');
+    const pubPath   = path.join(keyDir, 'public.key');
+    const secPath   = path.join(keyDir, 'secret.key');
+    let publicKeyB64, secretKeyB64;
+    if (fs.existsSync(pubPath) && fs.existsSync(secPath)) {
+        publicKeyB64 = fs.readFileSync(pubPath, 'utf8').trim();
+        secretKeyB64 = fs.readFileSync(secPath, 'utf8').trim();
+    } else {
+        const kp = generateKeyPair();
+        publicKeyB64 = kp.publicKey;
+        secretKeyB64 = kp.secretKey;
+        fs.writeFileSync(pubPath, publicKeyB64);
+        fs.writeFileSync(secPath, secretKeyB64, { mode: 0o600 });
+    }
+
+    // Keys store
+    const keysPath = path.join(lbeDir, 'config/keys.json');
+    const keysStore = fs.existsSync(keysPath)
+        ? JSON.parse(fs.readFileSync(keysPath, 'utf8'))
+        : { schemaVersion: '1', defaultKeyId, trustedKeys: {} };
+
+    for (const keyId of [defaultKeyId, signerKeyId]) {
+        if (!keysStore.trustedKeys[keyId]) {
+            keysStore.trustedKeys[keyId] = {
+                publicKey: publicKeyB64,
+                notBefore: nowIso,
+                expiresAt,
+                validFrom: nowIso,
+                validUntil: expiresAt,
+                deprecated: false,
+            };
+        }
+    }
+    keysStore.defaultKeyId = defaultKeyId;
+    fs.writeFileSync(keysPath, JSON.stringify(keysStore, null, 2));
+
+    // Policy
+    const policyPath = path.join(lbeDir, 'config/policy.default.json');
+    let policyObj;
+    if (fs.existsSync(policyPath)) {
+        policyObj = JSON.parse(fs.readFileSync(policyPath, 'utf8'));
+    } else {
+        policyObj = {
+            default: 'DENY',
+            version: '1.0.0',
+            createdAt: nowIso,
+            security: {
+                maxClockSkewSec: 600,
+                maxPolicyCreatedAtSkewSec: 31536000,
+                defaultRateLimit: { windowSec: 60, maxRequests: 30 }
+            },
+            requesters: {
+                'agent:gpt': {
+                    allowAdapters: ['noop', 'shell'],
+                    allowCommands: ['RUN_SHELL'],
+                    rateLimit: { windowSec: 60, maxRequests: 30 },
+                    filesystem: { roots: [cwd], denyPatterns: ['**/.git/**', '**/secrets/**', '**/*.key'] },
+                    exec: { allowCmds: ['ls', 'node', 'python', 'echo'], denyCmds: ['rm', 'chmod', 'chown', 'curl', 'wget', 'su', 'sudo'] }
+                }
+            }
+        };
+        fs.writeFileSync(policyPath, JSON.stringify(policyObj, null, 2));
+    }
+
+    // Policy signature
+    const sigResult = createPolicySignatureEnvelope({ policyObj, secretKeyB64, keyId: signerKeyId });
+    if (sigResult.ok) {
+        fs.writeFileSync(path.join(lbeDir, 'config/policy.sig.json'), JSON.stringify(sigResult.envelope, null, 2));
+    }
+
+    return { defaultKeyId, secretKeyB64, publicKeyB64 };
+}
+
+// ─── Agent governance files ───────────────────────────────────────────────────
+// Generated once by init so every AI agent auto-discovers LBE without the user
+// needing to explain it. Logic and internals are never mentioned — only the API.
+
+function agentContractContent() {
+    return `# LBE Governance Contract
+
+This project has LetterBlack LBE (Local-first execution Governance) active.
+
+## Your role as an agent
+
+Every file write, delete, and shell command must go through the LBE executor.
+The executor validates each action against the project policy and audits it.
+
+## How to perform actions
+
+\`\`\`js
+import { createLocalExecutor } from '@letterblack/lbe-exec';
+const lbe = createLocalExecutor({ rootDir: process.cwd() });
+
+await lbe.writeFile('output/report.md', content);
+await lbe.readFile('src/config.json');
+await lbe.patchFile('src/index.js', patch);
+await lbe.deleteFile('tmp/scratch.txt');
+await lbe.runShell('node', ['scripts/build.js']);
+\`\`\`
+
+## What you must never do
+
+- Call fs.* or child_process.* directly
+- Modify \`.lbe/policy.json\` directly — propose a rule via \`lbe.policy.proposeRule()\`
+- Attempt to bypass or disable the executor
+
+## Proposing a policy rule
+
+\`\`\`js
+const proposal = lbe.policy.proposeRule({
+  effect: 'deny', type: 'path', pattern: 'secrets/**',
+  from: 'agent: these files should never be modified'
+});
+// Return proposal to the user — never call lbe.policy.addRule() yourself.
+\`\`\`
+
+## Result shape
+
+\`{ ok: boolean, decision: 'allow' | 'deny' | 'observe', executed: boolean }\`
+
+## Files
+
+- Policy: \`.lbe/policy.json\`
+- Audit:  \`.lbe/audit.jsonl\`
+- Status: \`npx lbe-exec status\`
+`;
+}
+
+function writeAgentContract(cwd) {
+    const lbeDir = path.join(cwd, '.lbe');
+    fs.mkdirSync(lbeDir, { recursive: true });
+    fs.writeFileSync(path.join(lbeDir, 'AGENT_CONTRACT.md'), agentContractContent());
+}
+
+// Migrate legacy root-level LBE files into .lbe/ so the workspace stays clean.
+function migrateLegacyRootFiles(cwd) {
+    const lbeDir = path.join(cwd, '.lbe');
+    fs.mkdirSync(lbeDir, { recursive: true });
+    const migrations = [
+        ['lbe.policy.json',    '.lbe/policy.json'],
+        ['lbe.workspace.json', '.lbe/workspace.json'],
+    ];
+    const removed = [];
+    for (const [src, dest] of migrations) {
+        const srcPath  = path.join(cwd, src);
+        const destPath = path.join(cwd, dest);
+        if (fs.existsSync(srcPath) && !fs.existsSync(destPath)) {
+            fs.renameSync(srcPath, destPath);
+            removed.push(src + ' → ' + dest);
+        } else if (fs.existsSync(srcPath)) {
+            fs.unlinkSync(srcPath);          // dest already exists — just drop the old file
+            removed.push(src + ' (removed — .lbe/ version exists)');
+        }
+    }
+    // Remove files that should never have been created in the project root
+    const toDelete = ['CLAUDE.md', path.join('.github', 'copilot-instructions.md')];
+    for (const rel of toDelete) {
+        const p = path.join(cwd, rel);
+        // Only remove if it contains the lbe-governance marker — don't touch user files
+        if (fs.existsSync(p)) {
+            const content = fs.readFileSync(p, 'utf8');
+            if (content.includes('lbe-governance') || content.includes('LetterBlack LBE')) {
+                fs.unlinkSync(p);
+                removed.push(rel + ' (removed — LBE-generated file)');
+            }
+        }
+    }
+    return removed;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+export async function initCommand(opts = {}) {
+    const cwd     = process.cwd();
+    const yes     = opts.yes || opts.y || !process.stdin.isTTY;
+    const lbeDir  = path.join(cwd, '.lbe');
+    fs.mkdirSync(lbeDir, { recursive: true });
+    const outPath = path.join(lbeDir, 'workspace.json');
+
+    // 1. Scan
+    console.log('\nScanning workspace...\n');
+    const { projectTypes, primaryType, semantics, enforcement } = scanWorkspace(cwd);
+
+    // 2. Show summary
+    console.log(formatSummary(projectTypes, semantics, enforcement));
+    console.log('');
+
+    // 3. Ask once (unless --yes or non-interactive)
+    let finalEnforcement = enforcement;
+    if (!yes) {
+        const answer = await ask('Accept? [Y = accept / s = strict / r = relaxed / n = cancel] ');
+        if (answer === 'n') {
+            console.log('Cancelled.');
+            return { success: false };
+        }
+        if (answer === 's') finalEnforcement = applyStrict(enforcement);
+        if (answer === 'r') finalEnforcement = applyRelaxed(enforcement);
+    }
+
+    // 4. Write lbe.workspace.json
+    const contract = {
+        lbe:         true,
+        version:     '0.4.0',
+        state:       'local',
+        projectTypes,
+        primaryType,
+        semantics,
+        enforcement: finalEnforcement,
+    };
+    fs.writeFileSync(outPath, JSON.stringify(contract, null, 2));
+    console.log('✓ Wrote .lbe/workspace.json');
+
+    // 5. Crypto setup (silent)
+    setupCrypto(cwd);
+    const localPolicyPath = path.join(lbeDir, 'policy.json');
+    if (!fs.existsSync(localPolicyPath)) {
+        fs.writeFileSync(localPolicyPath, JSON.stringify({ version: 1, mode: 'observe', workspace: cwd, rules: [] }, null, 2) + '\n');
+    }
+    const localAuditPath = path.join(lbeDir, 'audit.jsonl');
+    if (!fs.existsSync(localAuditPath)) fs.writeFileSync(localAuditPath, '');
+    console.log('✓ Keys and policy ready  (.lbe/)');
+
+    // 6. Agent contract inside .lbe/ only — no CLAUDE.md, no .github/ changes
+    writeAgentContract(cwd);
+    console.log('✓ Agent contract written  →  .lbe/AGENT_CONTRACT.md');
+
+    // 7. Migrate any legacy root files from previous LBE versions
+    const migrated = migrateLegacyRootFiles(cwd);
+    if (migrated.length) {
+        console.log('\n✓ Migrated legacy files:');
+        for (const m of migrated) console.log('  ' + m);
+    }
+
+    console.log('\nDone. All LBE state is in .lbe/');
+    console.log('Run  npx lbe-exec status  to verify.\n');
+
+    return { success: true, contract };
+}

package/src/cli/commands/integrityCheck.js

@@ -0,0 +1,57 @@
+// src/cli/commands/integrityCheck.js
+// Controller integrity commands
+
+import path from 'path';
+import { performIntegrityCheck, writeIntegrityManifest } from '../../core/integrity.js';
+
+function toBoolean(value, defaultValue = false) {
+    if (value === undefined) return defaultValue;
+    if (value === true || value === false) return value;
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes') return true;
+    if (normalized === 'false' || normalized === '0' || normalized === 'no') return false;
+    return defaultValue;
+}
+
+export async function integrityCheckCommand(opts) {
+    const strict = toBoolean(opts.strict, false) || toBoolean(opts['integrity-strict'], false);
+    const manifestPath = opts.manifest
+        ? path.resolve(opts.manifest)
+        : path.resolve(opts['integrity-manifest'] || '.lbe/config/integrity.manifest.json');
+    const jsonOutput = toBoolean(opts.json, true);
+
+    const result = await performIntegrityCheck({
+        manifestPath,
+        strict
+    });
+
+    if (jsonOutput) {
+        console.log(JSON.stringify({
+            ok: result.valid,
+            valid: result.valid,
+            skipped: result.skipped === true,
+            strict,
+            manifestPath,
+            checkedFiles: result.checkedFiles,
+            mismatches: result.mismatches || [],
+            missing: result.missing || [],
+            reason: result.reason || null,
+            message: result.message
+        }, null, 2));
+    } else {
+        console.log(result.message);
+    }
+
+    process.exit(result.valid ? 0 : 8);
+}
+
+export async function integrityGenerateCommand(opts) {
+    const outputPath = path.resolve(opts.out || opts.output || opts.manifest || '.lbe/config/integrity.manifest.json');
+    const result = writeIntegrityManifest({ outputPath });
+    console.log(JSON.stringify({
+        ok: true,
+        outputPath: result.outputPath,
+        fileCount: result.fileCount
+    }, null, 2));
+    process.exit(0);
+}