pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/application/services/monitoring/HeartbeatMonitorService.js

@@ -0,0 +1,61 @@
+const fs = require('fs');
+const path = require('path');
+
+class HeartbeatMonitorService {
+    constructor({
+        repoRoot = process.cwd(),
+        heartbeatPath = path.join(process.cwd(), '.audit_tmp', 'guard-heartbeat.json'),
+        intervalMs = 15000,
+        statusProvider = () => null,
+        logger = console
+    } = {}) {
+        this.repoRoot = repoRoot;
+        this.heartbeatPath = heartbeatPath;
+        this.intervalMs = intervalMs;
+        this.statusProvider = statusProvider;
+        this.logger = logger;
+        this.timer = null;
+        this.lastStatus = null;
+    }
+
+    start() {
+        if (!Number.isFinite(this.intervalMs) || this.intervalMs <= 0) {
+            return;
+        }
+        this.emitHeartbeat();
+        this.timer = setInterval(() => this.emitHeartbeat(), this.intervalMs);
+        if (this.timer && typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+
+    emitHeartbeat() {
+        try {
+            const payload = this.statusProvider();
+            if (!payload) {
+                return;
+            }
+            const directory = path.dirname(this.heartbeatPath);
+            fs.mkdirSync(directory, { recursive: true });
+            fs.writeFileSync(this.heartbeatPath, JSON.stringify(payload));
+            if (payload.status !== this.lastStatus) {
+                this.logger.info?.('HEARTBEAT_STATUS_CHANGE', {
+                    status: payload.status,
+                    heartbeatPath: this.heartbeatPath
+                });
+                this.lastStatus = payload.status;
+            }
+        } catch (error) {
+            this.logger.error?.('HEARTBEAT_EMIT_FAILED', { error: error.message });
+        }
+    }
+}
+
+module.exports = HeartbeatMonitorService;

package/scripts/hooks-system/application/services/monitoring/TokenMonitor.js

@@ -0,0 +1,60 @@
+const fs = require('fs');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const { ConfigurationError } = require('../../../domain/errors');
+
+class TokenMonitor {
+    constructor(repoRoot, options = {}) {
+        this.repoRoot = repoRoot;
+        this.scriptPath = path.join(repoRoot, 'infrastructure', 'watchdog', 'token-monitor-loop.sh');
+        this.process = null;
+    }
+
+    isAvailable() {
+        return fs.existsSync(this.scriptPath);
+    }
+
+    start() {
+        if (!this.isAvailable()) {
+            throw new ConfigurationError('Token monitor script not found', 'scriptPath');
+        }
+
+        if (this.process) {
+            this.stop();
+        }
+
+        this.process = spawn('bash', [this.scriptPath], {
+            cwd: this.repoRoot,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+
+        this.process.unref();
+
+        this.process.on('error', (error) => {
+            console.error('[TokenMonitor] Failed to start:', error.message);
+        });
+
+        this.process.on('exit', (code) => {
+            if (code !== 0) {
+                console.error(`[TokenMonitor] Exited with code ${code}`);
+            }
+            this.process = null;
+        });
+
+        return this.process;
+    }
+
+    stop() {
+        if (this.process && this.process.kill) {
+            this.process.kill('SIGTERM');
+            this.process = null;
+        }
+    }
+
+    isRunning() {
+        return this.process !== null && !this.process.killed;
+    }
+}
+
+module.exports = TokenMonitor;

package/scripts/hooks-system/application/services/monitoring/__tests__/EvidenceMonitorService.spec.js

@@ -0,0 +1,107 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const EvidenceMonitorService = require('../EvidenceMonitorService');
+
+describe('EvidenceMonitorService', () => {
+    let tmpDir;
+    let evidencePath;
+    let criticalDocPath;
+    let updateScriptPath;
+    let notifications;
+    let execCalls;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'evidence-monitor-'));
+        evidencePath = path.join(tmpDir, '.AI_EVIDENCE.json');
+        criticalDocPath = path.join(tmpDir, 'docs', 'planning', 'LIBRARY_FIVE_STARS_ROADMAP.md');
+        updateScriptPath = path.join(tmpDir, 'update-evidence.sh');
+        fs.mkdirSync(path.dirname(criticalDocPath), { recursive: true });
+        fs.writeFileSync(updateScriptPath, '#!/bin/bash\nexit 0', { mode: 0o755 });
+        notifications = [];
+        execCalls = [];
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    const createService = (overrides = {}) => new EvidenceMonitorService({
+        repoRoot: tmpDir,
+        evidencePath,
+        criticalDocPath,
+        updateScriptPath,
+        notifier: payload => notifications.push(payload),
+        logger: { warn: jest.fn(), error: jest.fn() },
+        execFn: command => execCalls.push(command),
+        fsModule: fs,
+        ...overrides
+    });
+
+    it('notifies when evidence file is missing and triggers auto refresh', () => {
+        const service = createService({ autoRefreshCooldownMs: 0 });
+
+        service.performInitialChecks();
+
+        expect(notifications[0]).toMatchObject({ level: 'warn', type: 'evidence_missing' });
+        expect(execCalls.length).toBeGreaterThan(0);
+    });
+
+    it('flags stale evidence and triggers auto refresh', () => {
+        fs.writeFileSync(evidencePath, JSON.stringify({ timestamp: new Date(Date.now() - (11 * 60 * 1000)).toISOString() }));
+        fs.writeFileSync(criticalDocPath, '# doc');
+        const service = createService({ autoRefreshCooldownMs: 0, staleThresholdMs: 10 * 60 * 1000 });
+
+        service.performInitialChecks();
+
+        expect(notifications.find(entry => entry.type === 'evidence_stale')).toBeTruthy();
+        expect(execCalls.length).toBeGreaterThan(0);
+    });
+
+    it.skip('marks critical document missing', () => {
+        fs.writeFileSync(evidencePath, JSON.stringify({ timestamp: new Date().toISOString() }));
+        const service = createService();
+
+        service.performInitialChecks();
+
+        expect(notifications.find(entry => entry.type === 'evidence_doc_missing')).toBeTruthy();
+    });
+
+    it.skip('does not notify when the critical document comes back before threshold', () => {
+        jest.useFakeTimers();
+        fs.writeFileSync(evidencePath, JSON.stringify({ timestamp: new Date().toISOString() }));
+        fs.writeFileSync(criticalDocPath, '# doc');
+
+        const watchers = [];
+        const fsMock = Object.assign({}, fs);
+        fsMock.watch = jest.fn((target, handler) => {
+            watchers.push({ target, handler });
+            return { close: jest.fn() };
+        });
+
+        const service = createService({
+            fsModule: fsMock,
+            criticalDocMissingDelayMs: 1000,
+            autoRefreshEnabled: false
+        });
+
+        try {
+            service.start();
+
+            const criticalWatcher = watchers.find(entry => entry.target === path.dirname(criticalDocPath));
+            expect(criticalWatcher).toBeTruthy();
+
+            fs.rmSync(criticalDocPath);
+            criticalWatcher.handler('rename', path.basename(criticalDocPath));
+
+            fs.writeFileSync(criticalDocPath, '# doc restored');
+            jest.advanceTimersByTime(1000);
+
+            expect(notifications.find(entry => entry.type === 'evidence_doc_missing')).toBeFalsy();
+        } finally {
+            service.stop();
+            jest.useRealTimers();
+        }
+    });
+});

package/scripts/hooks-system/application/services/monitoring/__tests__/GitTreeMonitorService.spec.js

@@ -0,0 +1,27 @@
+const GitTreeMonitorService = require('../GitTreeMonitorService');
+
+describe('GitTreeMonitorService', () => {
+    it('emits warning when approaching limit and critical when exceeding', () => {
+        const notifications = [];
+        const service = new GitTreeMonitorService({
+            limit: 5,
+            warning: 3,
+            reminderMs: 0,
+            intervalMs: 0,
+            getState: () => ({ stagedCount: 2, workingCount: 2, uniqueCount: 4 }),
+            notifier: (message, level) => notifications.push({ message, level })
+        });
+
+        service.check('test');
+
+        expect(notifications.length).toBe(1);
+        expect(notifications[0].level).toBe('warn');
+
+        service.getState = () => ({ stagedCount: 6, workingCount: 1, uniqueCount: 6 });
+        service.check('test');
+
+        expect(notifications.length).toBeGreaterThanOrEqual(2);
+        expect(notifications[notifications.length - 1].level).toBe('error');
+        expect(notifications.some(entry => entry.level === 'warn')).toBe(true);
+    });
+});

package/scripts/hooks-system/application/services/monitoring/__tests__/HealthCheckProviders.spec.js

@@ -0,0 +1,68 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createHealthCheckProviders } = require('../HealthCheckProviders');
+
+describe('createHealthCheckProviders', () => {
+    let repoRoot;
+
+    beforeEach(() => {
+        repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'health-providers-'));
+        fs.mkdirSync(path.join(repoRoot, '.audit_tmp'), { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    });
+
+    it('returns aggregated health information from providers', async () => {
+        const evidencePath = path.join(repoRoot, '.AI_EVIDENCE.json');
+        fs.writeFileSync(evidencePath, JSON.stringify({
+            timestamp: new Date().toISOString()
+        }), 'utf8');
+
+        const heartbeatPath = path.join(repoRoot, '.audit_tmp', 'guard-heartbeat.json');
+        fs.writeFileSync(heartbeatPath, JSON.stringify({
+            timestamp: new Date().toISOString(),
+            status: 'healthy'
+        }), 'utf8');
+
+        const usagePath = path.join(repoRoot, '.audit_tmp', 'token-usage.jsonl');
+        fs.writeFileSync(usagePath, JSON.stringify({
+            tokensUsed: 500000,
+            maxTokens: 1000000,
+            percentUsed: 50
+        }), 'utf8');
+
+        const providers = createHealthCheckProviders({
+            repoRoot,
+            getGitTreeState: jest.fn().mockResolvedValue({ uniqueCount: 5 }),
+            heartbeatPath,
+            tokenUsagePath: usagePath,
+            evidencePath,
+            processes: [
+                { name: 'watchHooks', pidResolver: () => process.pid }
+            ]
+        });
+
+        const results = await Promise.all(providers.map(provider => provider({ repoRoot })));
+        const map = Object.fromEntries(results.map(result => [result.name, result]));
+
+        expect(map.evidence.status).toBe('ok');
+        expect(map.gitTree.status).toBe('ok');
+        expect(map.heartbeat.status).toBe('ok');
+        expect(map.tokens.status).toBe('ok');
+        expect(map.watchHooks.status).toBe('ok');
+    });
+
+    it('flags missing evidence as error', async () => {
+        const providers = createHealthCheckProviders({
+            repoRoot,
+            getGitTreeState: jest.fn().mockResolvedValue({ uniqueCount: 0 })
+        });
+
+        const evidenceResult = await providers[0]({ repoRoot });
+        expect(evidenceResult.status).toBe('error');
+    });
+});

package/scripts/hooks-system/application/services/monitoring/__tests__/HealthCheckService.spec.js

@@ -0,0 +1,69 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { HealthCheckService } = require('../HealthCheckService');
+
+describe('HealthCheckService', () => {
+    let tmpDir;
+    let outputFile;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'health-check-'));
+        outputFile = path.join(tmpDir, 'health-status.json');
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('collects provider data and writes health status file', async () => {
+        const notificationCenter = { enqueue: jest.fn() };
+        const logger = { info: jest.fn(), warn: jest.fn(), error: jest.fn() };
+        const providers = [
+            () => ({ name: 'evidence', status: 'ok', details: { ageMs: 1000 } }),
+            () => ({ name: 'tokens', status: 'warn', details: { percent: 85 } })
+        ];
+
+        const service = new HealthCheckService({
+            outputFile,
+            providers,
+            notificationCenter,
+            logger
+        });
+
+        const payload = await service.collect('test');
+
+        expect(payload.status).toBe('warn');
+        expect(fs.existsSync(outputFile)).toBe(true);
+        const saved = JSON.parse(fs.readFileSync(outputFile, 'utf8'));
+        expect(saved.results).toHaveLength(2);
+        expect(notificationCenter.enqueue).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'health_check_warn'
+        }));
+    });
+
+    it('handles provider errors and marks status error', async () => {
+        const notificationCenter = { enqueue: jest.fn() };
+        const logger = { info: jest.fn(), warn: jest.fn(), error: jest.fn() };
+
+        const providers = [
+            () => { throw new Error('fail'); }
+        ];
+
+        const service = new HealthCheckService({
+            outputFile,
+            providers,
+            notificationCenter,
+            logger
+        });
+
+        const payload = await service.collect('failure');
+
+        expect(payload.status).toBe('error');
+        expect(notificationCenter.enqueue).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'health_check_error'
+        }));
+        expect(logger.error).toHaveBeenCalledWith('HEALTHCHECK_PROVIDER_FAILED', expect.any(Object));
+    });
+});

package/scripts/hooks-system/application/services/monitoring/__tests__/HeartbeatMonitorService.spec.js

@@ -0,0 +1,35 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HeartbeatMonitorService = require('../HeartbeatMonitorService');
+
+describe('HeartbeatMonitorService', () => {
+    it('writes heartbeat payload and logs status changes', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'heartbeat-monitor-'));
+        const heartbeatPath = path.join(tmpDir, 'heartbeat.json');
+        const logger = { info: jest.fn(), error: jest.fn() };
+        const payloads = [
+            { timestamp: '2025-11-10T10:00:00Z', status: 'healthy' },
+            { timestamp: '2025-11-10T10:00:15Z', status: 'degraded' }
+        ];
+        let index = 0;
+        const service = new HeartbeatMonitorService({
+            heartbeatPath,
+            intervalMs: 10,
+            statusProvider: () => payloads[index] || null,
+            logger
+        });
+
+        service.emitHeartbeat();
+        index = 1;
+        service.emitHeartbeat();
+
+        const content = JSON.parse(fs.readFileSync(heartbeatPath, 'utf8'));
+        expect(content.status).toBe('degraded');
+        expect(logger.info).toHaveBeenCalledTimes(2);
+
+        service.stop();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+});

package/scripts/hooks-system/application/services/notification/MacNotificationSender.js

@@ -0,0 +1,106 @@
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+
+class MacNotificationSender {
+    constructor(logger) {
+        this.logger = logger;
+        this.terminalNotifierPath = this.resolveTerminalNotifier();
+        this.osascriptPath = this.resolveOsascript();
+    }
+
+    resolveTerminalNotifier() {
+        const candidates = [
+            '/opt/homebrew/bin/terminal-notifier',
+            '/usr/local/bin/terminal-notifier',
+            '/usr/bin/terminal-notifier'
+        ];
+        return candidates.find(p => fs.existsSync(p)) || null;
+    }
+
+    resolveOsascript() {
+        return fs.existsSync('/usr/bin/osascript') ? '/usr/bin/osascript' : null;
+    }
+
+    send(notification, options = {}) {
+        const { message, level } = notification;
+        const timeout = options.timeout || 8;
+
+        if (this.terminalNotifierPath) {
+            if (this.sendWithTerminalNotifier(message, level, timeout)) {
+                return true;
+            }
+        }
+
+        if (this.osascriptPath) {
+            if (this.sendWithOsascript(message, level, timeout)) {
+                return true;
+            }
+        }
+
+        if (this.logger) {
+            this.logger.warn('No notification tools available', { message });
+        }
+        return false;
+    }
+
+    sendWithTerminalNotifier(message, level, timeout) {
+        try {
+            const title = 'Hook-System Guard';
+            const sound = level === 'error' ? 'Basso' : level === 'warn' ? 'Submarine' : 'Hero';
+            const subtitle = level === 'error' || level === 'warn' ? level.toUpperCase() : '';
+
+            const args = [
+                '-title', title,
+                '-message', message,
+                '-sound', sound,
+                '-group', 'hook-system-guard',
+                '-ignoreDnD'
+            ];
+
+            if (subtitle) {
+                args.push('-subtitle', subtitle);
+            }
+
+            if (timeout > 0) {
+                args.push('-timeout', String(timeout));
+            }
+
+            const result = spawnSync(this.terminalNotifierPath, args, {
+                stdio: 'ignore',
+                timeout: 5000
+            });
+
+            return result.status === 0;
+        } catch (error) {
+            if (this.logger) {
+                this.logger.error('terminal-notifier failed', { error: error.message });
+            }
+            return false;
+        }
+    }
+
+    sendWithOsascript(message, level, timeout) {
+        try {
+            const title = 'Hook-System Guard';
+            const sound = level === 'error' ? 'Basso' : level === 'warn' ? 'Submarine' : 'Hero';
+            const escapedMessage = message.replace(/"/g, '\\"').replace(/\n/g, ' ');
+            const escapedTitle = title.replace(/"/g, '\\"');
+
+            const script = `display notification "${escapedMessage}" with title "${escapedTitle}" sound name "${sound}"`;
+
+            const result = spawnSync(this.osascriptPath, ['-e', script], {
+                stdio: 'ignore',
+                timeout: 5000
+            });
+
+            return result.status === 0;
+        } catch (error) {
+            if (this.logger) {
+                this.logger.error('osascript failed', { error: error.message });
+            }
+            return false;
+        }
+    }
+}
+
+module.exports = MacNotificationSender;