pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/application/services/evidence/__tests__/EvidenceContextManager.spec.js

@@ -0,0 +1,98 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { EvidenceContextManager } = require('../EvidenceContextManager');
+
+describe('EvidenceContextManager', () => {
+    let repoRoot;
+    let evidencePath;
+
+    beforeEach(() => {
+        repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'evidence-manager-'));
+        evidencePath = path.join(repoRoot, '.AI_EVIDENCE.json');
+    });
+
+    afterEach(() => {
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    });
+
+    const writeEvidence = timestamp => {
+        fs.writeFileSync(evidencePath, JSON.stringify({
+            timestamp,
+            protocol_3_questions: { answered: true },
+            justification: 'test'
+        }), 'utf8');
+    };
+
+    it('detects stale evidence and triggers refresh', async () => {
+        const now = new Date();
+        const stale = new Date(now.getTime() - 10 * 60 * 1000).toISOString();
+        writeEvidence(stale);
+
+        const runCommand = jest.fn().mockResolvedValue({ stdout: 'ok' });
+        const manager = new EvidenceContextManager({
+            repoRoot,
+            runCommand,
+            thresholdSeconds: 60
+        });
+
+        const result = await manager.ensureFresh('test');
+
+        expect(result.refreshed).toBe(true);
+        expect(runCommand).toHaveBeenCalled();
+    });
+
+    it('skips refresh when evidence is recent', async () => {
+        writeEvidence(new Date().toISOString());
+
+        const runCommand = jest.fn();
+        const manager = new EvidenceContextManager({
+            repoRoot,
+            runCommand,
+            thresholdSeconds: 300
+        });
+
+        const result = await manager.ensureFresh('test');
+
+        expect(result.refreshed).toBe(false);
+        expect(runCommand).not.toHaveBeenCalled();
+    });
+
+    it('handles missing evidence by refreshing', async () => {
+        const runCommand = jest.fn().mockResolvedValue({ stdout: 'ok' });
+        const manager = new EvidenceContextManager({
+            repoRoot,
+            runCommand
+        });
+
+        await manager.ensureFresh('missing');
+
+        expect(runCommand).toHaveBeenCalled();
+    });
+
+    it('prevents concurrent refresh executions', async () => {
+        writeEvidence('1970-01-01T00:00:00Z');
+
+        const resolverQueue = [];
+        const runCommand = jest.fn().mockImplementation(
+            () =>
+                new Promise(resolve => {
+                    resolverQueue.push(resolve);
+                })
+        );
+
+        const manager = new EvidenceContextManager({
+            repoRoot,
+            runCommand
+        });
+
+        const promiseA = manager.refresh({ reason: 'a' });
+        const promiseB = manager.refresh({ reason: 'b' });
+        expect(runCommand).toHaveBeenCalledTimes(1);
+        resolverQueue.forEach(resolve => resolve({ stdout: 'ok' }));
+        await promiseA;
+        const skipped = await promiseB;
+        expect(skipped.status).toBe('skipped');
+    });
+});

package/scripts/hooks-system/application/services/guard/GuardAutoManagerService.js

@@ -0,0 +1,169 @@
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const { toErrorMessage } = require('../../../infrastructure/utils/error-utils');
+const GuardHeartbeatMonitor = require('./GuardHeartbeatMonitor');
+const GuardLockManager = require('./GuardLockManager');
+const GuardProcessManager = require('./GuardProcessManager');
+const GuardEventLogger = require('./GuardEventLogger');
+const GuardRecoveryService = require('./GuardRecoveryService');
+const GuardConfig = require('./GuardConfig');
+const GuardNotificationHandler = require('./GuardNotificationHandler');
+const GuardMonitorLoop = require('./GuardMonitorLoop');
+const GuardHealthReminder = require('./GuardHealthReminder');
+
+class GuardAutoManagerService {
+    constructor({
+        repoRoot = process.cwd(),
+        logger = console,
+        notificationCenter = null,
+        fsModule = fs,
+        childProcess = { spawnSync },
+        timers = { setInterval, clearInterval },
+        env = process.env,
+        processRef = process,
+        heartbeatMonitor = null
+    } = {}) {
+        this.process = processRef;
+
+        // Configuration & Infrastructure
+        this.config = new GuardConfig(env);
+        this.eventLogger = new GuardEventLogger({ repoRoot, logger, fsModule });
+        this.lockManager = new GuardLockManager({ repoRoot, logger, fsModule });
+        this.processManager = new GuardProcessManager({ repoRoot, logger, fsModule, childProcess });
+
+        // Monitors & Handlers
+        this.heartbeatMonitor = heartbeatMonitor || new GuardHeartbeatMonitor({
+            repoRoot, logger, fsModule, env
+        });
+        this.notificationHandler = new GuardNotificationHandler(notificationCenter, this.eventLogger, this.config);
+        this.recoveryService = new GuardRecoveryService({
+            repoRoot, logger, startScript: this.processManager.startScript,
+            notificationHandler: this.notificationHandler, restartCooldownMs: this.config.restartCooldownMs
+        });
+
+        // Loops
+        this.monitorLoop = new GuardMonitorLoop(timers, this.config.monitorIntervalMs, () => this.monitorTick(), this.eventLogger);
+        this.healthReminder = new GuardHealthReminder(timers, this.notificationHandler, this.config);
+
+        // State
+        this.lastHeartbeatState = { healthy: true, reason: 'healthy' };
+        this.lastHeartbeatRestart = 0;
+        this.shuttingDown = false;
+    }
+
+    notifyUser(message, level = 'info', metadata = {}) {
+        if (!this.notificationHandler) return;
+        this.notificationHandler.notify(message, level, metadata);
+    }
+
+    start() {
+        if (!this.lockManager.acquireLock()) {
+            this.eventLogger.log('Another guard auto manager instance detected. Exiting.');
+            return false;
+        }
+        this.lockManager.writePidFile();
+        this.eventLogger.log('Guard auto manager started');
+
+        this.ensureSupervisor('initial-start');
+        this._startReminder();
+        this.monitorLoop.start();
+        this.registerProcessHooks();
+        return true;
+    }
+
+    monitorTick() {
+        if (this.shuttingDown) return;
+
+        if (!this.processManager.isSupervisorRunning()) {
+            this.handleMissingSupervisor();
+            return;
+        }
+
+        const heartbeat = this.heartbeatMonitor.evaluate();
+        if (!heartbeat.healthy) {
+            this.handleUnhealthyHeartbeat(heartbeat);
+            return;
+        }
+
+        if (!this.lastHeartbeatState.healthy || this.lastHeartbeatState.reason !== 'healthy') {
+            this._startReminder();
+        }
+        this.lastHeartbeatState = { healthy: true, reason: 'healthy' };
+    }
+
+    handleMissingSupervisor() {
+        this.lastHeartbeatState = { healthy: false, reason: 'missing-supervisor' };
+        this.eventLogger.recordEvent('Guard supervisor no se encuentra en ejecución; reinicio automático.');
+        this.ensureSupervisor('missing-supervisor');
+    }
+
+    handleUnhealthyHeartbeat(heartbeat) {
+        this.lastHeartbeatState = { healthy: false, reason: heartbeat.reason };
+
+        if (this.heartbeatMonitor.shouldRestart(heartbeat.reason)) {
+            const now = Date.now();
+            if (now - this.lastHeartbeatRestart >= this.config.heartbeatRestartCooldownMs) {
+                this.eventLogger.log(`Heartbeat degraded (${heartbeat.reason}); attempting supervisor ensure.`);
+                this.lastHeartbeatRestart = now;
+                this.ensureSupervisor(`heartbeat-${heartbeat.reason}`);
+            } else {
+                this.eventLogger.log(`Heartbeat degraded (${heartbeat.reason}); restart suppressed (cooldown).`);
+                this.eventLogger.recordEvent(`Heartbeat degradado (${heartbeat.reason}); reinicio omitido por cooldown.`);
+            }
+        } else {
+            this.eventLogger.recordEvent(`Heartbeat en estado ${heartbeat.reason}; reinicio no requerido.`);
+        }
+    }
+
+    shutdown() {
+        if (this.shuttingDown) return;
+        this.shuttingDown = true;
+        this.eventLogger.log('Shutting down guard auto manager');
+
+        this.monitorLoop.stop();
+        this.healthReminder.stop();
+
+        if (this.config.stopSupervisorOnExit) {
+            const result = this.processManager.stopSupervisor();
+            if (!result.success) this.eventLogger.log(`Error stopping supervisor: ${result.error?.message}`);
+        }
+        this.cleanup();
+    }
+
+    registerProcessHooks() {
+        const shutdownHandler = () => this.shutdown();
+        ['SIGINT', 'SIGTERM', 'SIGHUP'].forEach(sig => this.process.on(sig, shutdownHandler));
+        this.process.on('exit', () => this.cleanup());
+        this.process.on('uncaughtException', e => {
+            this.eventLogger.log(`Uncaught exception: ${e.stack || e.message}`);
+            this.shutdown();
+        });
+        this.process.on('unhandledRejection', r => {
+            this.eventLogger.log(`Unhandled rejection: ${toErrorMessage(r)}`);
+            this.shutdown();
+        });
+    }
+
+    cleanup() {
+        this.lockManager.removePidFile();
+        this.lockManager.releaseLock();
+        this.healthReminder.stop();
+    }
+
+    ensureSupervisor(reason) {
+        const ensured = this.recoveryService.ensureSupervisor(reason, this.eventLogger);
+        if (ensured && (reason === 'initial-start' || reason.startsWith('heartbeat-'))) {
+            this._startReminder();
+        }
+    }
+
+    _startReminder() {
+        this.healthReminder.start(() =>
+            !this.shuttingDown &&
+            this.lastHeartbeatState.healthy &&
+            this.lastHeartbeatState.reason === 'healthy'
+        );
+    }
+}
+
+module.exports = { GuardAutoManagerService };

package/scripts/hooks-system/application/services/guard/GuardConfig.js

@@ -0,0 +1,15 @@
+class GuardConfig {
+    constructor(env = process.env) {
+        this.healthyReminderIntervalMs = Number(env.GUARD_AUTOSTART_HEALTHY_INTERVAL || 0);
+        this.heartbeatNotifyCooldownMs = Number(env.GUARD_AUTOSTART_NOTIFY_COOLDOWN || 60000);
+        this.healthyReminderCooldownMs = Number(
+            env.GUARD_AUTOSTART_HEALTHY_COOLDOWN || (this.healthyReminderIntervalMs > 0 ? this.healthyReminderIntervalMs : 0)
+        );
+        this.heartbeatRestartCooldownMs = Number(env.GUARD_AUTOSTART_HEARTBEAT_COOLDOWN || 60000);
+        this.monitorIntervalMs = Number(env.GUARD_AUTOSTART_MONITOR_INTERVAL || 5000);
+        this.restartCooldownMs = Number(env.GUARD_AUTOSTART_RESTART_COOLDOWN || 2000);
+        this.stopSupervisorOnExit = env.GUARD_AUTOSTART_STOP_SUPERVISOR_ON_EXIT !== 'false';
+    }
+}
+
+module.exports = GuardConfig;

package/scripts/hooks-system/application/services/guard/GuardEventLogger.js

@@ -0,0 +1,70 @@
+const fs = require('fs');
+const path = require('path');
+
+class GuardEventLogger {
+    constructor({
+        repoRoot = process.cwd(),
+        logger = console,
+        fsModule = fs
+    } = {}) {
+        this.repoRoot = repoRoot;
+        this.logger = logger;
+        this.fs = fsModule;
+
+        this.tmpDir = path.join(this.repoRoot, '.audit_tmp');
+        this.eventLogPath = path.join(this.tmpDir, 'guard-events.log');
+
+        try {
+            if (!this.fs.existsSync(this.tmpDir)) {
+                this.fs.mkdirSync(this.tmpDir, { recursive: true });
+            }
+            if (!this.fs.existsSync(this.eventLogPath)) {
+                this.fs.writeFileSync(this.eventLogPath, '', { encoding: 'utf8' });
+            }
+        } catch (error) {
+            if (this.logger?.debug) {
+                this.logger.debug('GUARD_EVENT_LOGGER_INIT_ERROR', { error: error.message });
+            }
+        }
+    }
+
+    log(message, data = {}) {
+        if (this.logger?.info) {
+            this.logger.info(message, data);
+        } else if (this.logger === console) {
+            console.error(message, data);
+        }
+    }
+
+    recordEvent(message) {
+        if (!message) {
+            return;
+        }
+        try {
+            const entry = `[${this.formatLocalTimestamp()}] ${message}`;
+            this.fs.appendFileSync(this.eventLogPath, `${entry}\n`, { encoding: 'utf8' });
+        } catch (error) {
+            this.log(`Error recording event: ${error.message}`);
+        }
+    }
+
+    formatLocalTimestamp(date = new Date()) {
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, '0');
+        const day = String(date.getDate()).padStart(2, '0');
+        const hours = String(date.getHours()).padStart(2, '0');
+        const minutes = String(date.getMinutes()).padStart(2, '0');
+        const seconds = String(date.getSeconds()).padStart(2, '0');
+        const milliseconds = String(date.getMilliseconds()).padStart(3, '0');
+
+        const offsetMinutes = date.getTimezoneOffset();
+        const sign = offsetMinutes <= 0 ? '+' : '-';
+        const absolute = Math.abs(offsetMinutes);
+        const offsetHours = String(Math.floor(absolute / 60)).padStart(2, '0');
+        const offsetMins = String(absolute % 60).padStart(2, '0');
+
+        return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${milliseconds}${sign}${offsetHours}:${offsetMins}`;
+    }
+}
+
+module.exports = GuardEventLogger;

package/scripts/hooks-system/application/services/guard/GuardHealthReminder.js

@@ -0,0 +1,54 @@
+class GuardHealthReminder {
+    constructor(timers, notificationHandler, config) {
+        this.timers = timers;
+        this.notificationHandler = notificationHandler;
+        this.config = config;
+        this.timer = null;
+        this.lastReminderAt = 0;
+    }
+
+    start(checkHealthCallback) {
+        this.stop();
+
+        const { healthyReminderIntervalMs } = this.config;
+        if (!Number.isFinite(healthyReminderIntervalMs) || healthyReminderIntervalMs <= 0) {
+            return;
+        }
+
+        this.timer = this.timers.setInterval(() => {
+            this._tick(checkHealthCallback);
+        }, healthyReminderIntervalMs);
+
+        if (this.timer && typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+
+    stop() {
+        if (this.timer) {
+            this.timers.clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+
+    _tick(checkHealthCallback) {
+        if (!checkHealthCallback()) return;
+
+        const now = Date.now();
+        const { healthyReminderIntervalMs, healthyReminderCooldownMs } = this.config;
+
+        const cooldown = Number.isFinite(healthyReminderCooldownMs) && healthyReminderCooldownMs > 0
+            ? healthyReminderCooldownMs
+            : healthyReminderIntervalMs;
+
+        if (cooldown > 0 && now - this.lastReminderAt < cooldown) return;
+
+        this.lastReminderAt = now;
+        this.notificationHandler.notify('Guard-supervisor en ejecución.', 'info', {
+            reason: 'healthy-reminder',
+            cooldownMs: cooldown
+        });
+    }
+}
+
+module.exports = GuardHealthReminder;

package/scripts/hooks-system/application/services/guard/GuardHeartbeatMonitor.js

@@ -0,0 +1,94 @@
+const fs = require('fs');
+const path = require('path');
+
+class GuardHeartbeatMonitor {
+    constructor({
+        repoRoot = process.cwd(),
+        logger = console,
+        fsModule = fs,
+        env = process.env
+    } = {}) {
+        this.repoRoot = repoRoot;
+        this.logger = logger;
+        this.fs = fsModule;
+        this.env = env;
+
+        const heartbeatRelative = env.HOOK_GUARD_HEARTBEAT_PATH || path.join('.audit_tmp', 'guard-heartbeat.json');
+        this.heartbeatPath = path.isAbsolute(heartbeatRelative)
+            ? heartbeatRelative
+            : path.join(this.repoRoot, heartbeatRelative);
+
+        this.heartbeatMaxAgeMs = Number(
+            env.GUARD_AUTOSTART_HEARTBEAT_MAX_AGE || env.HOOK_GUARD_HEARTBEAT_MAX_AGE || 60000
+        );
+
+        this.heartbeatRestartReasons = new Set(
+            (env.GUARD_AUTOSTART_HEARTBEAT_RESTART || 'missing,stale,invalid,degraded')
+                .split(',')
+                .map(entry => entry.trim().toLowerCase())
+                .filter(Boolean)
+        );
+    }
+
+    evaluate() {
+        if (!Number.isFinite(this.heartbeatMaxAgeMs) || this.heartbeatMaxAgeMs <= 0) {
+            return { healthy: true, reason: 'disabled' };
+        }
+
+        try {
+            if (!this.fs.existsSync(this.heartbeatPath)) {
+                return { healthy: false, reason: 'missing' };
+            }
+
+            const raw = this.fs.readFileSync(this.heartbeatPath, 'utf8');
+            if (!raw) {
+                return { healthy: false, reason: 'missing' };
+            }
+
+            let data;
+            try {
+                data = JSON.parse(raw);
+            } catch (e) {
+                return { healthy: false, reason: 'invalid', error: e.message };
+            }
+
+            const timestamp = Date.parse(data.timestamp);
+            if (!Number.isFinite(timestamp)) {
+                return { healthy: false, reason: 'invalid', data };
+            }
+
+            const age = Date.now() - timestamp;
+            if (age > this.heartbeatMaxAgeMs) {
+                return { healthy: false, reason: 'stale', data };
+            }
+
+            const status = (data.status || '').toLowerCase();
+            if (status && status !== 'healthy') {
+                return { healthy: false, reason: status, data };
+            }
+
+            const guardRunning = Boolean(data?.guard?.running);
+            const tokenRunning = Boolean(data?.tokenMonitor?.running);
+            if (!guardRunning || !tokenRunning) {
+                return { healthy: false, reason: 'degraded', data };
+            }
+
+            return { healthy: true, reason: 'healthy', data };
+        } catch (error) {
+            this.logger.error(`Heartbeat evaluation error: ${error.message}`);
+            return { healthy: false, reason: 'error', error };
+        }
+    }
+
+    shouldRestart(reason) {
+        if (!this.heartbeatRestartReasons.size) {
+            return false;
+        }
+        if (this.heartbeatRestartReasons.has('*')) {
+            return true;
+        }
+        return this.heartbeatRestartReasons.has(reason);
+    }
+}
+
+module.exports = GuardHeartbeatMonitor;

package/scripts/hooks-system/application/services/guard/GuardLockManager.js

@@ -0,0 +1,72 @@
+const fs = require('fs');
+const path = require('path');
+
+class GuardLockManager {
+    constructor({
+        repoRoot = process.cwd(),
+        logger = console,
+        fsModule = fs
+    } = {}) {
+        this.repoRoot = repoRoot;
+        this.logger = logger;
+        this.fs = fsModule;
+
+        this.tmpDir = path.join(this.repoRoot, '.audit_tmp');
+        this.lockDir = path.join(this.tmpDir, 'guard-auto-manager.lock');
+        this.pidFile = path.join(this.repoRoot, '.guard-auto-manager.pid');
+
+        // Ensure tmp dir exists
+        try {
+            if (!this.fs.existsSync(this.tmpDir)) {
+                this.fs.mkdirSync(this.tmpDir, { recursive: true });
+            }
+        } catch (error) {
+            // Race condition or directory already exists is fine, but we log for debugging
+            if (this.logger?.debug) {
+                this.logger.debug('GUARD_LOCK_MANAGER_INIT_DEBUG', { error: error.message });
+            }
+        }
+    }
+
+    acquireLock() {
+        try {
+            this.fs.mkdirSync(this.lockDir, { recursive: false });
+            return true;
+        } catch (error) {
+            if (this.logger?.debug) {
+                this.logger.debug('GUARD_LOCK_ACQUIRE_FAILED', { error: error.message });
+            }
+            return false;
+        }
+    }
+
+    releaseLock() {
+        try {
+            if (this.fs.existsSync(this.lockDir)) {
+                this.fs.rmdirSync(this.lockDir);
+            }
+        } catch (error) {
+            this.logger.warn?.(`Error releasing lock: ${error.message}`);
+        }
+    }
+
+    writePidFile() {
+        try {
+            this.fs.writeFileSync(this.pidFile, String(process.pid), { encoding: 'utf8' });
+        } catch (error) {
+            this.logger.warn?.(`Error writing PID file: ${error.message}`);
+        }
+    }
+
+    removePidFile() {
+        try {
+            if (this.fs.existsSync(this.pidFile)) {
+                this.fs.unlinkSync(this.pidFile);
+            }
+        } catch (error) {
+            this.logger.warn?.(`Error removing PID file: ${error.message}`);
+        }
+    }
+}
+
+module.exports = GuardLockManager;

package/scripts/hooks-system/application/services/guard/GuardMonitorLoop.js

@@ -0,0 +1,29 @@
+class GuardMonitorLoop {
+    constructor(timers, intervalMs, tickCallback, logger) {
+        this.timers = timers;
+        this.intervalMs = intervalMs;
+        this.tickCallback = tickCallback;
+        this.logger = logger;
+        this.timer = null;
+    }
+
+    start() {
+        this.stop();
+        this.timer = this.timers.setInterval(() => {
+            try {
+                this.tickCallback();
+            } catch (error) {
+                this.logger.log(`Monitor error: ${error.message}`);
+            }
+        }, this.intervalMs);
+    }
+
+    stop() {
+        if (this.timer) {
+            this.timers.clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+
+module.exports = GuardMonitorLoop;

package/scripts/hooks-system/application/services/guard/GuardNotificationHandler.js

@@ -0,0 +1,36 @@
+class GuardNotificationHandler {
+    constructor(notificationCenter, eventLogger, config) {
+        this.notificationCenter = notificationCenter;
+        this.eventLogger = eventLogger;
+        this.config = config;
+        this.lastNotificationState = { reason: null, at: 0 };
+    }
+
+    notify(message, level = 'info', options = {}) {
+        if (!message) return;
+
+        const { reason = null, cooldownMs = this.config.heartbeatNotifyCooldownMs } = options;
+        if (reason) {
+            const now = Date.now();
+            if (this.lastNotificationState.reason === reason && now - this.lastNotificationState.at < cooldownMs) {
+                this.eventLogger.log(`NOTIFY_SUPPRESSED|${reason}|cooldown`);
+                return;
+            }
+            this.lastNotificationState = { reason, at: now };
+        }
+
+        this.eventLogger.recordEvent(`${(level || 'info').toUpperCase()} ${message}`);
+        this.eventLogger.log(`NOTIFY|${level}|${message}`);
+
+        if (this.notificationCenter && typeof this.notificationCenter.enqueue === 'function') {
+            this.notificationCenter.enqueue({
+                message,
+                level,
+                type: `guard_auto_manager_${reason || level}`,
+                metadata: { reason, cooldownMs }
+            });
+        }
+    }
+}
+
+module.exports = GuardNotificationHandler;