Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
import { describe, expect, it } from 'vitest';
import { readdirSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
API_TOKEN_SCOPES_DOC_URL,
CONFIGURATION_DOC_URL,
MIGRATION_GUIDE_DOC_URL,
PRIVACY_DOC_URL,
PROXY_AUTH_DOC_URL,
README_DOC_URL,
SECURITY_DOC_URL,
TERMS_DOC_URL,
TROUBLESHOOTING_DOC_URL,
SHIPPED_DOCS_ROOT,
getShippedDocUrl,
} from '@/utils/docsLinks';
import { DIAGNOSTICS_PANEL_COPY } from '@/utils/diagnosticsPresentation';
import { renderDocMarkdown } from '@/features/docs/docMarkdown';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const frontendRoot = path.resolve(__dirname, '..', '..', '..');
const repoRoot = path.resolve(frontendRoot, '..');
const runtimeDocsLinkScanTimeoutMs = 15_000;
function getRuntimeSourceFiles(dir: string): string[] {
const entries = readdirSync(dir, { withFileTypes: true });
const files: string[] = [];
for (const entry of entries) {
const entryPath = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (entry.name === '__tests__') {
continue;
}
files.push(...getRuntimeSourceFiles(entryPath));
continue;
}
if (!entry.isFile()) {
continue;
}
if (!/\.(ts|tsx)$/.test(entry.name)) {
continue;
}
if (/(\.test|\.spec)\.(ts|tsx)$/.test(entry.name)) {
continue;
}
files.push(entryPath);
}
return files;
}
describe('docsLinks', () => {
const memoryFAQ = () => {
const faq = readFileSync(path.join(repoRoot, 'docs', 'FAQ.md'), 'utf8');
const article = document.createElement('article');
article.innerHTML = renderDocMarkdown(
faq.split('### High memory usage?')[1].split('\n### ')[0],
'FAQ',
);
return article;
};
it('makes the resident-memory FAQ lead to the shipped passive recipe', () => {
const link = memoryFAQ().querySelector(
'a[href="/docs/TROUBLESHOOTING#memory-use-keeps-growing"]',
);
expect(link?.textContent).toBe('read-only memory checks');
const source = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8');
expect(readFileSync(path.join(frontendRoot, 'public/docs/TROUBLESHOOTING.md'), 'utf8')).toBe(
source,
);
// Full-guide heading/navigation coverage lives in troubleshootingEntryGuide.
// This FAQ regression checks the actual destination section, not an unrelated
// sample elsewhere in the ever-growing troubleshooting guide.
const heading = '### Memory use keeps growing';
const sections = source.split(`${heading}\n`);
expect(sections).toHaveLength(2);
const memorySection = sections[1].split('\n### ')[0];
const guide = document.createElement('article');
guide.innerHTML = renderDocMarkdown(`${heading}\n${memorySection}`, 'TROUBLESHOOTING');
expect(guide.querySelector('#memory-use-keeps-growing')?.textContent).toBe(
'Memory use keeps growing',
);
expect(guide.textContent).toContain('Pulse resident-memory sample');
});
it('keeps the resident-memory FAQ from sacrificing history or claiming a leak', () => {
const article = memoryFAQ();
const text = article.textContent?.replace(/\s+/g, ' ');
expect(text).toContain("container usage from Pulse's resident memory (RSS)");
expect(text).toContain('a high LXC or Docker chart alone does not establish a leak');
expect(text).toContain('Do not shorten retention, slow polling, restart Pulse or drop caches');
expect(text).toContain('Shorter retention removes history');
expect(text).toContain('slower polling can delay monitoring');
expect(text).toContain('neither establishes the cause');
expect(text).toContain('stop sampling and prioritise safe recovery');
expect(article.querySelector('pre')).toBeNull();
expect(readFileSync(path.join(frontendRoot, 'public/docs/FAQ.md'), 'utf8')).toBe(
readFileSync(path.join(repoRoot, 'docs/FAQ.md'), 'utf8'),
);
});
it('publishes the API and metrics history references exactly as written', () => {
// The in-app docs serve these copies; the history route's accepted
// resourceType list must not differ between the two.
for (const guide of ['API.md', 'METRICS_HISTORY.md']) {
expect(readFileSync(path.join(frontendRoot, 'public/docs', guide), 'utf8')).toBe(
readFileSync(path.join(repoRoot, 'docs', guide), 'utf8'),
);
}
});
it('keeps report collection precautions usable without unpublished documentation links', () => {
for (const form of ['bug_report.yml', 'v6_rc_feedback.yml']) {
const source = readFileSync(path.join(repoRoot, '.github', 'ISSUE_TEMPLATE', form), 'utf8');
expect(source).toContain(
'do not run it during backups, freeze/thaw or an unresponsive-host incident',
);
expect(source).toContain('downloads that result without running checks again');
expect(source).toContain('Review files and screenshots locally before posting');
expect(source).not.toMatch(/https:\/\/github\.com\/rcourtman\/Pulse\/blob\/[^\s)]+\/docs\//);
}
});
const probeGuides = () =>
[
readFileSync(path.join(repoRoot, 'docs', 'CONFIGURATION.md'), 'utf8')
.split('### External probes (Pro)')[1]
.split('### ICMP probe privileges')[0],
readFileSync(path.join(repoRoot, 'docs', 'UNIFIED_AGENT.md'), 'utf8')
.split('## External Probes (Pro)')[1]
.split('## Custom metrics')[0],
].map((section) => section.replace(/\s+/g, ' '));
it('keeps external probes dependent on server-side alert delivery', () => {
for (const guide of probeGuides()) {
expect(guide).toContain('The agent does not send notifications directly.');
expect(guide).toContain(
'Pulse server must be running and able to reach the notification destination',
);
expect(guide).toContain('agent cannot deliver Pulse alerts in its place');
expect(guide).toContain('not proof');
expect(guide).not.toContain('cannot disappear silently');
}
});
it('explains the existing missing-report and bounded-buffer limits', () => {
for (const guide of probeGuides()) {
expect(guide).toContain('five minutes or three check intervals');
expect(guide).toContain('server receipt time');
expect(guide).toContain('host-offline alert');
expect(guide).toContain('policies');
expect(guide).toMatch(/changes (?:its|the) observation location/);
}
const agentGuide = probeGuides()[1];
expect(agentGuide).toContain('up to 200 observations');
expect(agentGuide).toContain('Oldest pending observations are dropped');
expect(agentGuide).toContain('agent restart loses the queue');
expect(agentGuide).toContain('not a complete outage record');
// These limits come from the current implementation, not a new policy.
const monitor = readFileSync(
path.join(repoRoot, 'internal', 'monitoring', 'availability_probe_agent.go'),
'utf8',
);
expect(monitor).toContain('availabilityProbeStaleFloor = 5 * time.Minute');
expect(monitor).toContain('target.EffectivePollIntervalSecs()) * 3 * time.Second');
const agent = readFileSync(
path.join(repoRoot, 'internal', 'hostagent', 'availability.go'),
'utf8',
);
expect(agent).toContain('availabilityPendingCapacity = 200');
});
it('links independent outage coverage without a permanent Mobile guarantee', () => {
for (const guide of probeGuides()) {
expect(guide).toContain('TROUBLESHOOTING.md#no-alert-when-pulse-power-or-internet-goes-down');
expect(guide).toContain('independently reachable notification destination');
expect(guide).toContain('authorised test environment');
expect(guide).toContain('Existing paired Pulse Mobile/Relay users');
expect(guide).toContain('31 March 2027');
expect(guide).toContain('Relay is no longer sold');
expect(guide).toContain('not a permanent substitute');
expect(guide).toContain('[Mobile retirement](RELAY.md)');
expect(guide).not.toContain('push covers the dark-site case');
}
});
it('matches the existing observation-location editor and compatibility fields', () => {
for (const guide of probeGuides()) {
expect(guide).toContain('Observation locations');
expect(guide).toContain('This Pulse server');
expect(guide).toContain('not a universal outage');
expect(guide).not.toContain('Run from');
expect(guide).not.toContain('an assigned check is not also run locally');
}
const api = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
expect(api).toContain('`observationLocationIds` - Observation locations');
expect(api).toContain('`pulse:local` for this Pulse server');
expect(api).toContain('`agent:<host-agent-id>` for a connected agent');
expect(api).toContain('omit `observationLocationIds`');
expect(api).toContain('clear `probeAgentId` to `""`');
});
it('documents alert history entries carrying only the newest evidence envelope', () => {
const api = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
expect(api).toContain(
'`GET /api/alerts/history` — each entry carries at most one `evidence` envelope, the newest',
);
expect(api).toContain('`operationalRecord.evidenceIds` keeps the full list');
});
it('documents alert configuration saves as replacing only the keys they send', () => {
const api = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
expect(api).toContain('`PUT /api/alerts/config` — replaces only the top-level keys the body');
expect(api).toContain('a key left out keeps its stored value');
});
it('documents the Pulse Pro runtime switch routes and their scopes', () => {
const api = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
expect(api).toContain('`GET /api/updates/pro-runtime` (`settings:read`)');
expect(api).toContain('`POST /api/updates/pro-runtime/apply` (`settings:write`)');
const routes = readFileSync(
path.join(repoRoot, 'internal', 'api', 'router_routes_registration.go'),
'utf8',
);
expect(routes).toContain(
'"/api/updates/pro-runtime", RequireAdmin(r.config, RequireScope(config.ScopeSettingsRead,',
);
expect(routes).toContain(
'"/api/updates/pro-runtime/apply", RequireAdmin(r.config, RequireScope(config.ScopeSettingsWrite,',
);
});
it('documents instance administration refusing organization-bound tokens', () => {
const api = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
expect(api).toContain('tenant organization gets `403` whatever its scopes');
expect(api).toContain('Token management is instance administration');
const guard = readFileSync(
path.join(repoRoot, 'internal', 'api', 'security_setup_fix.go'),
'utf8',
);
expect(guard).toContain(
'ensureTokenSettingsScope(w, req, record, scope) && refuseOrgBoundToken(w, req, record)',
);
});
it('documents network discovery without the removed AI Discovery routes', () => {
const api = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
expect(api).toContain('`POST /api/discover` (admin, `settings:write`)');
expect(api).not.toContain('/api/discovery');
expect(api).not.toContain('### AI Discovery');
});
it('separates server removal from persistent-data erasure', () => {
const installation = readFileSync(path.join(repoRoot, 'docs', 'INSTALL.md'), 'utf8');
const removal = installation.split('## 🗑️ Uninstall')[1];
expect(removal).toContain('stops monitoring and alert delivery');
expect(removal).toContain('Keep persistent\ndata by default');
expect(removal).toContain('every effective data path');
expect(removal).toContain('[full-state backup](MIGRATION.md#full-state-recovery)');
expect(removal).toContain('A configuration export\nalone is not a full backup');
expect(removal).toContain('Let any in-progress Pulse update finish');
expect(removal).toContain('without a\nkeep-data prompt');
expect(removal).toContain('Do not remove\nthe service account');
expect(removal).toContain('Do not delete `/bin/update` unless');
expect(removal).toContain('Removing the server does not remove agents');
// Pin the copyable recipes, not merely the surrounding warnings. The old
// Docker/root commands erased the complete data store as part of removal.
const commands = [...removal.matchAll(/```bash\n([\s\S]*?)```/g)].flatMap((match) =>
match[1]
.replace(/\\\n\s*/g, ' ')
.trim()
.split('\n')
.map((line) => line.replace(/\s+/g, ' ').trim()),
);
expect(commands).toEqual([
'docker stop pulse',
'docker rm pulse',
'docker compose stop pulse',
'docker compose rm pulse',
'kubectl scale deployment pulse --namespace pulse --replicas=0',
'sudo systemctl disable --now pulse-update.timer',
'sudo systemctl disable --now pulse.service',
]);
});
it('bounds container-removal advice to retained persistent mounts', () => {
const installation = readFileSync(path.join(repoRoot, 'docs', 'INSTALL.md'), 'utf8');
const docker = (
installation.split('### Docker and Compose: retain the data mount')[1] ?? ''
).split('### Kubernetes:')[0];
expect(docker).toContain('persistent named volume or bind');
expect(docker).toContain("container's writable layer or temporary storage");
expect(docker).toContain('`--rm` can also delete anonymous volumes');
expect(docker).toContain('**existing** project');
expect(docker).toContain('reattach the **same** data mount');
expect(docker).toContain('prefixes volume names');
expect(docker).toContain('Do not add `-v`/`--volumes`');
expect(docker).not.toContain('docker rm -f');
expect(docker).not.toContain('docker volume rm');
});
it('does not promise Helm retention where the current chart owns the claim', () => {
const installation = readFileSync(path.join(repoRoot, 'docs', 'INSTALL.md'), 'utf8');
const kubernetes = (
installation.split('### Kubernetes: check claim ownership before uninstalling')[1] ?? ''
).split('### Systemd / Proxmox LXC:')[0];
expect(kubernetes).toContain('Do not assume `helm uninstall pulse -n pulse` retains data');
expect(kubernetes).toContain('without a keep policy');
expect(kubernetes).toContain('reclaim policy can delete its backing data');
expect(kubernetes).toContain('`persistence.existingClaim`');
expect(kubernetes).toContain('`emptyDir` storage, lost when the pod is removed');
expect(kubernetes.indexOf('After verifying persistent storage and its backup')).toBeLessThan(
kubernetes.indexOf('```bash'),
);
expect(kubernetes).toContain('suspend any controller');
const chart = readFileSync(
path.join(repoRoot, 'deploy', 'helm', 'pulse', 'templates', 'pvc.yaml'),
'utf8',
);
expect(chart).toContain('kind: PersistentVolumeClaim');
expect(chart).toContain('(not .Values.persistence.existingClaim)');
expect(chart).not.toContain('helm.sh/resource-policy');
const values = readFileSync(
path.join(repoRoot, 'deploy', 'helm', 'pulse', 'values.yaml'),
'utf8',
);
expect(values.split('persistence:')[1].split('server:')[0]).toContain('annotations: {}');
});
it('keeps custom systemd server help on the signed non-root install path', () => {
const installation = readFileSync(path.join(repoRoot, 'docs', 'INSTALL.md'), 'utf8');
const custom = installation
.split('<summary><strong>Manual or custom systemd services (advanced)</strong></summary>')[1]
.split('</details>')[0];
expect(custom).toContain('use the signed installer above');
expect(custom).toContain('`User=pulse`, `Group=pulse`');
expect(custom).toContain('`ProtectSystem=strict` and `ProtectHome=true`');
expect(custom).toContain('`LoadState=loaded`');
expect(custom).toContain('not that a root service is running');
expect(custom).toContain('an empty `User=`');
expect(custom).toContain('the installer preserves existing service units during updates');
expect(custom).toContain('Do not overwrite a working unit, change only its service user');
expect(custom).toContain('preserve the data directory and its encryption');
expect(custom).toContain('separate host **agent** has different privilege requirements');
const commands = [...custom.matchAll(/```bash\n([\s\S]*?)```/g)].map((match) => match[1]);
expect(commands).toHaveLength(1);
expect(commands[0]).toContain('systemctl show pulse.service');
expect(commands[0]).toContain('--property=LoadState');
expect(Math.max(...commands[0].split('\n').map((line) => line.length))).toBeLessThan(34);
expect(commands[0]).not.toMatch(/--property=(Environment|ExecStart)|sudo|tee|install -m/);
expect(installation).not.toContain('sudo tee /etc/systemd/system/pulse.service');
expect(installation).not.toContain('ExecStart=/usr/local/bin/pulse');
});
it('keeps TrueNAS setup acceptance separate from a system-information probe', () => {
const truenas = readFileSync(path.join(repoRoot, 'docs', 'TRUENAS.md'), 'utf8');
const setup = truenas.split('## Quick Start')[1].split('## Creating a TrueNAS API Key')[0];
expect(setup).toContain('it does not validate inventory or metric collection');
expect(setup).toContain('an elapsed interval is not proof');
expect(setup).toContain('[polling checks](#stale-truenas-data)');
expect(setup).not.toContain('Data appears within one configured polling cycle');
const noData = truenas
.split('### No data appearing after adding connection')[1]
.split('### Inventory works')[0];
expect(noData).toContain('Pools,\n datasets, disks and alerts can still fail');
expect(noData).toContain('does not establish live CPU, memory');
expect(truenas).toContain('Some older builds, including Pulse\n6.4.1 and 6.4.5');
expect(truenas).toContain('use the inventory observation time rather than the test time');
expect(truenas).toContain('do not copy a token or cookie');
expect(truenas).toContain('Do not post the full connection response');
});
it('keeps restored Proxmox node network details in the candidate packet', () => {
const releaseNotes = readFileSync(
path.join(repoRoot, 'docs', 'releases', 'RELEASE_NOTES_v6.4.0-rc.1.md'),
'utf8',
);
expect(releaseNotes).toContain(
'Proxmox node details show the configured interface names and IPv4/IPv6',
);
});
// These now resolve to the in-app viewer route rather than the raw asset.
// The raw file is still served at the same path plus .md, which is what the
// viewer fetches, so the source remains reachable.
it('returns canonical shipped doc URLs', () => {
expect(SHIPPED_DOCS_ROOT).toBe('/docs');
expect(getShippedDocUrl('PRIVACY.md')).toBe('/docs/PRIVACY');
expect(PRIVACY_DOC_URL).toBe('/docs/PRIVACY');
expect(README_DOC_URL).toBe('/docs/README');
expect(MIGRATION_GUIDE_DOC_URL).toBe('/docs/MIGRATION_UNIFIED_NAV');
expect(TROUBLESHOOTING_DOC_URL).toBe('/docs/TROUBLESHOOTING');
expect(CONFIGURATION_DOC_URL).toBe('/docs/CONFIGURATION');
expect(PROXY_AUTH_DOC_URL).toBe('/docs/PROXY_AUTH');
expect(SECURITY_DOC_URL).toBe('/docs/SECURITY');
expect(TERMS_DOC_URL).toBe('/docs/TERMS');
expect(API_TOKEN_SCOPES_DOC_URL).toBe('/docs/CONFIGURATION');
});
it('keeps shipped docs content synced with repo docs', () => {
// Derived from what is actually shipped rather than a hand-maintained
// list, so a doc copied into public/docs can never silently drift from
// its repo source and a new one cannot be added without a source.
const shippedDocsRoot = path.join(frontendRoot, 'public', 'docs');
// Shipped from the repository root rather than docs/.
const rootSourcedDocs = new Set([
'SECURITY.md',
'TERMS.md',
'ARCHITECTURE.md',
'CONTRIBUTING.md',
]);
function collectShippedDocs(dir: string, prefix = ''): string[] {
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
if (entry.isDirectory()) {
return collectShippedDocs(path.join(dir, entry.name), relative);
}
return entry.name.endsWith('.md') ? [relative] : [];
});
}
const docPairs = collectShippedDocs(shippedDocsRoot)
.sort()
.map((target) => ({
source: rootSourcedDocs.has(target)
? path.join(repoRoot, target)
: path.join(repoRoot, 'docs', ...target.split('/')),
target,
}));
expect(docPairs.length).toBeGreaterThan(0);
expect(docPairs.map(({ target }) => target)).toContain('UPGRADE_v6.md');
for (const { source, target } of docPairs) {
const rootDoc = readFileSync(source, 'utf8');
const publicDoc = readFileSync(path.join(frontendRoot, 'public', 'docs', target), 'utf8');
expect(publicDoc).toBe(rootDoc);
expect(publicDoc).not.toContain('https://github.com/rcourtman/Pulse/blob/main/');
}
});
it('keeps reverse-proxy help explicit about forwarded HTTPS and peer trust', () => {
const proxy = readFileSync(path.join(repoRoot, 'docs', 'REVERSE_PROXY.md'), 'utf8');
const configuration = readFileSync(path.join(repoRoot, 'docs', 'CONFIGURATION.md'), 'utf8');
const setup = proxy
.split('## Before configuring the proxy')[1]
?.split('## ⚡ Quick Configs')[0];
expect(setup).toBeDefined();
expect(setup).toContain('configured immediate peer');
expect(setup).toContain('PULSE_TRUSTED_PROXY_CIDRS=127.0.0.1/32');
expect(setup).toContain('::1/128');
expect(setup).toContain('Wildcard ranges `0.0.0.0/0` and `::/0` are rejected');
expect(setup).toContain('not an authentication bypass');
expect(setup).toContain('[proxy authentication guide](PROXY_AUTH.md)');
expect(setup).toContain('including its Header Trust Boundary');
const nginx = proxy.split('### Nginx')[1].split('### Caddy')[0];
expect(nginx).toContain('HTTPS `server` block');
expect(nginx).toContain('proxy_set_header X-Forwarded-Proto $scheme;');
expect(nginx).toContain('proxy_set_header X-Forwarded-For $remote_addr;');
expect(nginx).toContain('proxy_set_header X-Forwarded-Host $host;');
expect(nginx).toContain('proxy_set_header Forwarded "";');
expect(proxy).not.toContain('$proxy_add_x_forwarded_for');
const troubleshooting = proxy.split('### "HTTPS: HTTP only"')[1].split('### Other Issues')[0];
expect(troubleshooting).toContain('Adding the header alone is not sufficient');
expect(troubleshooting).toContain('inside** its\n`reverse_proxy` block');
expect(troubleshooting).toContain('does not verify authentication, WebSockets or proxy');
expect(configuration).toContain('REVERSE_PROXY.md#before-configuring-the-proxy');
expect(configuration).toContain('forwarded client IP, scheme, host and port');
});
it('keeps configuration transfer separate from full-state recovery', () => {
const migration = readFileSync(path.join(repoRoot, 'docs', 'MIGRATION.md'), 'utf8');
const agent = readFileSync(path.join(repoRoot, 'docs', 'UNIFIED_AGENT.md'), 'utf8');
const scope = migration
.split('### Configuration transfer')[1]
.split('### Full-state recovery')[0];
expect(scope).toContain('Proxmox VE, PBS and PMG');
expect(scope).toContain('| TrueNAS, vSphere and Machine Availability');
expect(scope).toContain('SSO configuration **is included**');
expect(scope).toContain(
'Server-side host/Docker/Kubernetes agent inventory and enrolment state',
);
expect(migration).toContain('not a full backup of the installation');
expect(migration).toContain('Stop Pulse before taking that');
expect(migration).toContain('matching `.encryption.key`');
expect(migration).toContain('reload/apply failure');
expect(migration).toContain('it does not merge');
expect(migration).toContain('UNIFIED_AGENT.md#moving-pulse-to-a-new-address');
expect(migration).not.toContain('Update the `--token` flag');
expect(migration).not.toContain('Restored in < 5 minutes');
expect(migration).not.toContain('re-enable in Settings');
expect(agent).toContain('restores API-token records, not the server-side');
expect(agent).toContain('MIGRATION.md#configuration-transfer');
});
it('keeps lockout and incident reporting guidance safe for the affected client', () => {
const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8');
const recovery = troubleshooting.split('### Recovery Mode')[1].split('\n---')[0];
expect(recovery).toContain('[I forgot my password](#i-forgot-my-password)');
expect(recovery).toContain('browser-bound recovery');
expect(recovery).toContain('A successful curl response does not unlock a separate');
expect(recovery).toContain('remote and reverse-proxy');
expect(recovery).not.toContain('generate_token');
expect(recovery).not.toMatch(/```(?:bash|sh)[\s\S]*?X-Recovery-Token/);
const help = troubleshooting.split('## 🆘 Getting Help')[1];
expect(help).toContain('Do not repeat an update, outage or notification storm');
expect(help).toContain(DIAGNOSTICS_PANEL_COPY.exportGithubLabel);
expect(help).toContain('#collect-diagnostics-safely');
expect(help).toContain('Review before posting');
expect(help).toContain('session cookies, webhook URLs');
expect(help).toContain('If installation never started Pulse');
});
it('separates live diagnostics from private local downloads and manual sharing review', () => {
const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8');
const collection = troubleshooting
.split('### Collect diagnostics safely')[1]
.split('\n### ')[0]
.replace(/\s+/g, ' ');
expect(collection).toContain('live Proxmox/PBS API and guest-agent requests');
expect(collection).toContain('Do not run it during a backup, freeze/thaw');
expect(collection).toContain('unresponsive-host incident');
expect(collection).toContain('does not prove that normal monitoring has recovered');
expect(collection).toContain('without running the checks again');
expect(collection).toContain('not an upload');
expect(collection).toContain(DIAGNOSTICS_PANEL_COPY.exportFullLabel);
expect(collection).toContain(DIAGNOSTICS_PANEL_COPY.exportGithubLabel);
expect(collection).toContain('not a guarantee');
expect(collection).toContain('review it before sharing');
expect(collection).toContain('Do not paste a **Copy as cURL** command');
});
it('keeps port troubleshooting specific without exposing deployment credentials', () => {
const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8');
const ports = troubleshooting.split("### Port change didn't take effect")[1].split('\n### ')[0];
expect(ports).toContain('CONFIGURATION.md#common-overrides-environment-variables');
expect(ports).toContain('`PORT` alias applies only when `FRONTEND_PORT` is unset');
expect(ports).toContain('`frontendPort` in `system.json` has no effect');
expect(ports).toContain('separate agent listener, not the web UI port');
expect(ports).toContain('`systemctl is-active pulse`');
expect(ports).toContain('`sudo systemctl daemon-reload`');
expect(ports).toContain('inside\n the Pulse container, not on the Proxmox host');
expect(ports).toContain('`docker compose up -d pulse`');
expect(ports).toContain('same image and mounted data volume');
expect(ports).toContain('Restarting an existing container does not apply a new port mapping');
expect(ports).toContain('do not delete the volume');
expect(ports).toContain('Do not post full service environments');
expect(ports).not.toContain('--property=Environment');
expect(ports).not.toMatch(
/`(?:sudo )?(?:systemctl (?:status|cat)|docker inspect|docker compose config)[^`]*`(?! output)/,
);
});
it('explains container CPU scales without inventing a zero or forcing an alert', () => {
const docker = readFileSync(path.join(repoRoot, 'docs', 'DOCKER.md'), 'utf8');
const cpu = docker
.split('## Container CPU readings\n')[1]
.split('\n---')[0]
.replace(/\s+/g, ' ');
expect(cpu).toContain("Docker/Podman host's total CPU capacity");
expect(cpu).toContain('100% for one logical CPU');
expect(cpu).toContain('CPU count reported for the runtime host');
expect(cpu).toContain("not the physical Proxmox host's CPUs");
expect(cpu).toContain("not utilisation of the container's own CPU quota or cpuset");
expect(cpu).toContain('not an assumption about your host');
expect(cpu).toContain('v6.5.0-rc.1');
expect(cpu).toContain('not change stored readings or the values used by CPU alert evaluation');
expect(cpu).toContain('unavailable data, not a measured zero');
expect(cpu).toContain('Do not divide Pulse History again');
expect(cpu).toContain('separate sampling intervals can legitimately differ');
expect(cpu).toContain('Active does not prove fresh CPU samples');
expect(cpu).toContain('not that an alert should fire or that its notification was delivered');
expect(cpu).toContain('Do not restart workloads, create CPU load, lower alert thresholds');
expect(cpu).toContain('no forced alert test is needed');
const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8');
const entry = troubleshooting
.split('#### Container CPU differs from Docker or Podman stats\n')[1]
.split('\n#### ')[0]
.replace(/\s+/g, ' ');
expect(entry).toContain('DOCKER.md#container-cpu-readings');
expect(entry).toContain('reported runtime host CPU count');
expect(entry).toContain('same container and time interval');
expect(entry).toContain('unavailable, not zero');
expect(entry).toContain('Do not restart workloads, create CPU load or lower alert thresholds');
});
it('keeps clone identity recovery separate from destructive OS or credential resets', () => {
const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8');
const agentGuide = readFileSync(path.join(repoRoot, 'docs', 'UNIFIED_AGENT.md'), 'utf8');
const shortGuide = troubleshooting
.split('#### Docker hosts appearing/disappearing')[1]
.split('\n### ')[0];
const cloneGuide = agentGuide.split('### Duplicate Agents')[1].split('\n### ')[0];
expect(shortGuide).toContain('UNIFIED_AGENT.md#duplicate-agents');
for (const section of [shortGuide, cloneGuide]) {
expect(section).toContain('saved');
expect(section).toContain('Agent Doctor');
expect(section).toContain('original host unchanged');
expect(section).not.toContain('systemd-machine-id-setup');
expect(section).not.toMatch(/(?:sudo\s+)?rm\s+(?:-\S+\s+)*\/etc\/machine-id/);
}
expect(cloneGuide).toContain('argument wins over the environment variable');
expect(cloneGuide).toContain('PULSE_AGENT_ID_FILE');
expect(cloneGuide).toContain('Environment="PULSE_AGENT_ID=vm-clone-02"');
expect(cloneGuide).toContain('fresh, distinct IDs');
expect(cloneGuide).toContain('does not split or recover historical');
expect(cloneGuide).toContain('Do not upload `connection.env`, token files');
expect(cloneGuide).toContain('do not delete tokens, re-enrol');
});
it('ships a bounded maintenance example separately from incident snoozing', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const maintenance = apiReference
.split('### Resource Maintenance and Operator State')[1]
.split('### Fleet Connections')[0];
const example = JSON.parse(/```json\s*([\s\S]*?)```/.exec(maintenance)![1]);
expect(Date.parse(example.maintenanceEndAt)).toBeGreaterThan(
Date.parse(example.maintenanceStartAt),
);
expect(example.maintenanceScope).toBe('resource_and_descendants');
expect(maintenance).toContain('PUT replaces the whole record');
expect(maintenance).toContain('Do not DELETE the record unless you also intend');
expect(apiReference).toContain('](#resource-maintenance-and-operator-state)');
});
it('ships the Pulse Mobile retirement in the published API reference', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
expect(apiReference).toContain('## 📱 Relay / Pulse Mobile (retiring 31 March 2027)');
expect(apiReference).not.toContain('Mobile Remote Access');
});
it('keeps report narration behind both POST and the token spending scope', () => {
const handler = readFileSync(
path.join(repoRoot, 'internal', 'api', 'metrics_reporting_handlers.go'),
'utf8',
);
const single = handler
.split('func (h *ReportingHandlers) HandleGenerateReport(')[1]
.split('\nfunc ')[0];
const fleet = handler
.split('func (h *ReportingHandlers) generateMultiReportFromBody(')[1]
.split('\nfunc ')[0];
const caller = handler.split('func reportCallerMayUseAI(')[1].split('\nfunc ')[0];
const resolver = handler
.split('func (h *ReportingHandlers) resolveNarrator(')[1]
.split('\nfunc ')[0];
// The shared resolver owns spending permission; the handler still owns
// GET's deterministic path. Behavioural Go tests exercise every caller.
expect(single).toMatch(
/if r\.Method == http\.MethodPost \{\s*narrator, _, findings = h\.resolveNarrator\(r\.Context\(\)\)/,
);
expect(single.match(/h\.resolveNarrator\(/g)).toHaveLength(1);
expect(single).toMatch(
/if !reportCallerMayUseAI\(r\.Context\(\)\) \{\s*(?:\/\/[^\n]*\n\s*)*req\.Narrator = scopeLimitedReportNarrator\{\}/,
);
expect(single).toMatch(
/\} else \{\s*findings = h\.resolveExistingFindings\(r\.Context\(\)\)\s*req\.Narrator = getReportNarrator\{\}/,
);
expect(caller).toContain('internalauth.GetAPIToken(ctx).(*config.APITokenRecord)');
expect(caller).toMatch(/if !ok \|\| record == nil \{\s*return true/);
expect(caller).toContain('return record.HasScope(config.ScopeAIExecute)');
expect(resolver).toMatch(
/if !reportCallerMayUseAI\(ctx\) \{\s*return nil, nil, h\.resolveExistingFindings\(ctx\)\s*\}\s*return h\.narratorResolver\(ctx\)/,
);
expect(resolver.match(/h\.narratorResolver\(/g)).toHaveLength(1);
expect(fleet).toMatch(/_, fleetNarrator, findings := h\.resolveNarrator\(ctx\)/);
expect(fleet.match(/h\.resolveNarrator\(/g)).toHaveLength(1);
});
it('ships report help that separates read permission from AI spending', () => {
for (const guide of ['API.md', 'MSP.md']) {
const rootDoc = readFileSync(path.join(repoRoot, 'docs', guide), 'utf8');
expect(readFileSync(path.join(frontendRoot, 'public', 'docs', guide), 'utf8')).toBe(rootDoc);
expect(rootDoc).toContain('`POST /api/admin/reports/generate` (');
// Parse the actual report section, not both entire reference guides:
// unrelated installation/API tables are not this narration contract.
const reportSection =
guide === 'API.md'
? rootDoc
.split('### Advanced Reporting (Pro)')[1]
.split('### Queue and Dead-Letter Tools')[0]
: rootDoc.split('## Per-client reports')[1].split('## Licensing')[0];
const rendered = document.createElement('div');
rendered.innerHTML = renderDocMarkdown(reportSection, guide.replace('.md', ''));
const text = rendered.textContent?.replace(/\s+/g, ' ');
expect(text).toContain('Report generation uses settings:read.');
expect(text).toContain(
'For single-resource and fleet PDF narration, an API token also needs ai:execute (or full access).',
);
expect(text).toContain(
'Without it, the report still succeeds with a deterministic summary and no AI provider call',
);
expect(text).toContain('a single-resource PDF also explains the missing scope.');
expect(text).toContain(
'Browser sessions and server-run schedules keep their existing narration behaviour.',
);
expect(text).toContain('AI budgets still apply. GET and CSV never use AI narration');
}
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
// Keep both upstream route descriptions beside the shared spending guard.
expect(apiReference).toContain(
'API-token callers also need the `ai:execute` scope for AI narration.',
);
expect(apiReference).toContain(
'AI narration of the fleet summary follows the same rule as single reports: API-token callers need `ai:execute`, otherwise the deterministic summary is used. CSV output is never narrated.',
);
expect(apiReference).toContain('it never calls an AI provider');
expect(apiReference).toContain('`405` with `Allow: GET, POST`');
const msp = readFileSync(path.join(repoRoot, 'docs', 'MSP.md'), 'utf8');
expect(msp).not.toContain('`GET /api/admin/reports/generate` (single resource)');
});
it('ships credential-free Proxmox setup instructions and a separate token prompt', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shipped = readFileSync(path.join(frontendRoot, 'public', 'docs', 'API.md'), 'utf8');
const setup = apiReference.split('### Setup Script URL')[1].split('### Auto-Register')[0];
expect(shipped).toBe(apiReference);
expect(setup).toContain('identical credential-free commands');
expect(setup).toContain('`downloadURL` equals the tokenless `url`');
expect(setup).toContain('paste the token only at its prompt');
expect(setup).not.toContain('token-bearing `commandWithEnv`');
});
it('ships the saved-credential probe TLS override contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shipped = readFileSync(path.join(frontendRoot, 'public', 'docs', 'API.md'), 'utf8');
const probe = apiReference
.split('### Test Node (Legacy)')[1]
.split('### Refresh Cluster Nodes')[0];
expect(shipped).toBe(apiReference);
expect(probe).toContain('`POST /api/config/nodes/{id}/test` (admin, `settings:write`)');
expect(probe).toContain('optional JSON body can override `verifySSL` and `fingerprint`');
expect(probe).toContain('without changing the saved connection or credentials');
expect(probe).toMatch(/Omitted fields keep their\s+saved values/);
expect(probe).toContain('`false` to disable CA verification or `""` to clear the saved');
expect(probe).toMatch(/nonempty fingerprint remains enforced regardless of\s+`verifySSL`/);
expect(probe).toContain('Empty-body requests keep the saved TLS settings');
});
it('ships only the chat session routes Pulse Mobile still uses', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shipped = readFileSync(path.join(frontendRoot, 'public', 'docs', 'API.md'), 'utf8');
const sessions = apiReference.split('### Chat Sessions (Pulse Mobile)')[1].split('\n### ')[0];
expect(shipped).toBe(apiReference);
expect(sessions).toContain('these routes serve Pulse Mobile chat');
expect(sessions).toContain('`POST /api/ai/chat` (streaming)');
expect(sessions).toContain('`PATCH /api/ai/sessions/{id}` (rename)');
expect(sessions).toContain('`POST /api/ai/sessions/{id}/abort`');
// The web chat window that called these is retired.
for (const retired of [
'/summarize',
'/fork',
'/undo',
'/redo',
'/steer',
'/revert',
'/api/ai/question/',
'/api/ai/assistant/surface-tools',
'/api/ai/workflow-prompts/render',
]) {
expect(apiReference).not.toContain(retired);
}
});
it('ships the per-alert snooze and resume API contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
expect(apiReference).toContain('`POST /api/alerts/snooze`');
expect(apiReference).toContain('`POST /api/alerts/unsnooze`');
expect(apiReference).toContain(
'pauses delivery and escalation for up to 30 days while monitoring continues',
);
expect(apiReference).toContain('resumes normal policy without resolving the incident');
});
it('ships the Patrol weekly digest API contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
expect(apiReference).toContain('`GET /api/ai/patrol/digest`');
expect(apiReference).toContain('"what Patrol did for you" rollup');
expect(apiReference).toMatch(/nothing new is\s+persisted/);
expect(apiReference).toContain('docs/PATROL_WEEKLY_DIGEST.md');
});
it('documents the Patrol weekly summary report schedule kind for providers', () => {
const mspGuide = readFileSync(path.join(repoRoot, 'docs', 'MSP.md'), 'utf8');
expect(mspGuide).toContain('`patrol_digest`');
expect(mspGuide).toMatch(/Digest schedules are weekly and\s+email-only/);
});
it('ships the readable SSO identity and user deprovisioning contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const rbacGuide = readFileSync(path.join(repoRoot, 'docs', 'RBAC.md'), 'utf8');
expect(apiReference).toContain('`DELETE /api/admin/users/{username}`');
expect(apiReference).toContain('`displayName`, `email`, `providerType`, `providerId`');
expect(rbacGuide).toMatch(/revokes its active\s+sessions/);
expect(rbacGuide).toMatch(/Removal does not disable\s+the upstream IdP account/);
});
it('ships the Community SSO and Pro RBAC role boundary', () => {
const rbacGuide = readFileSync(path.join(repoRoot, 'docs', 'RBAC.md'), 'utf8');
const shippedRBACGuide = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'RBAC.md'),
'utf8',
);
const compactGuide = rbacGuide.replace(/\s+/g, ' ');
expect(shippedRBACGuide).toBe(rbacGuide);
expect(compactGuide).toContain(
'built-in roles can be automatically assigned based on group membership on every plan',
);
expect(compactGuide).toContain(
'Creating custom roles and manually managing user assignments require Pro RBAC',
);
expect(compactGuide).toContain('SSO authentication is not an administrator grant');
expect(compactGuide).toContain(
'map at least one trusted IdP group to the built-in `admin` role',
);
expect(compactGuide).toContain(
'never elevates that user merely because no local administrator is configured',
);
});
it('ships the configuration transfer authorization contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
const exportContract = apiReference
.split('### Export Configuration')[1]
?.split('### Import Configuration')[0]
?.replace(/\s+/g, ' ');
const importContract = apiReference
.split('### Import Configuration')[1]
?.split('---')[0]
?.replace(/\s+/g, ' ');
expect(exportContract).toContain('tenant manager');
expect(exportContract).toContain('settings:read');
expect(importContract).toContain('tenant manager');
expect(importContract).toContain('settings:write');
});
it('ships the retained notification recovery API contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
expect(apiReference).toContain('`POST /api/notifications/terminal-failures/retry`');
expect(apiReference).toContain('`POST /api/notifications/terminal-failures/dismiss`');
expect(apiReference).toContain('Existing per-attempt delivery history is preserved');
expect(apiReference).toContain('without deleting delivery history');
});
it('ships the mixed-retention notification delivery-log contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
const queueToolsSection = (reference: string) =>
reference.split('### Queue and Dead-Letter Tools')[1]?.split('\n### ')[0];
const canonicalQueueTools = queueToolsSection(apiReference);
expect(queueToolsSection(shippedAPIReference)).toBe(canonicalQueueTools);
const compactQueueTools = canonicalQueueTools?.replace(/\s+/g, ' ');
expect(compactQueueTools).toContain('`GET /api/notifications/delivery-log?limit=200`');
expect(compactQueueTools).toContain('Completed attempts are retained for 7 days');
expect(compactQueueTools).toContain('dead-letter attempts are retained for 30 days');
expect(compactQueueTools).toContain('`limit` defaults to 50 and is capped at 200');
});
it('ships the bulk active-alert delivery diagnosis contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
expect(apiReference).toContain(
'`GET /api/alerts/delivery-diagnosis?alertIdentifier=<alert-id>`',
);
expect(apiReference).toContain(
'omit `alertIdentifier` to get the diagnosis array for every active alert',
);
expect(apiReference).toContain('`GET /api/alerts/events?alertIdentifier=<alert-id>');
expect(apiReference).toContain('append-only alert event log');
});
it('ships the credential-safe external watchdog API contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
expect(apiReference).toContain('`GET /api/alerts/deadman/config`');
expect(apiReference).toContain('`PUT /api/alerts/deadman/config`');
expect(apiReference).toContain('`GET /api/alerts/deadman/status`');
expect(apiReference).toContain('`pingUrl` is `***REDACTED***` when present');
expect(apiReference).toContain('never includes the URL or endpoint fingerprint');
});
it('ships the truthful Patrol objective API contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedAPIReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
expect(shippedAPIReference).toBe(apiReference);
expect(apiReference).toContain('`POST /api/ai/patrol/objectives`');
expect(apiReference).toContain('`PATCH /api/ai/patrol/objectives/{id}`');
expect(apiReference).toContain('Clients cannot submit either');
expect(apiReference).toContain('validated, installed read-only observer with a live');
expect(apiReference).toContain('`409 patrol_objective_revision_conflict`');
});
it(
'keeps non-test frontend runtime files free of GitHub main doc links',
() => {
const runtimeFiles = getRuntimeSourceFiles(path.join(frontendRoot, 'src'));
for (const filePath of runtimeFiles) {
const source = readFileSync(filePath, 'utf8');
expect(
source,
`${path.relative(frontendRoot, filePath)} should use shipped/local docs owners`,
).not.toContain('https://github.com/rcourtman/Pulse/blob/main/');
}
},
runtimeDocsLinkScanTimeoutMs,
);
it('ships the Patrol cost preview and model guidance contract', () => {
const apiReference = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');
const shippedApiReference = readFileSync(
path.join(frontendRoot, 'public', 'docs', 'API.md'),
'utf8',
);
for (const reference of [apiReference, shippedApiReference]) {
expect(reference).toContain('`GET /api/ai/patrol/cost-preview`');
expect(reference).toContain('`GET /api/ai/patrol/model-guidance`');
expect(reference).toContain('recommended schedule');
}
});
});