Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Unit tests for the fleet console engine (services/fleet-console).
*
* Everything here is pure: URL extraction, probe classification, the scoring
* model, registry name parsing, badge rendering and the attention ranking. The
* network-facing parts are covered by running a real scan, which cannot live in
* a unit test suite.
*/
import { describe, it, expect } from 'vitest';
import { extractReadmeLinks, deploymentCandidates, isIgnoredHost } from '../services/fleet-console/src/extract-urls.js';
import { __testables as probeInternals, isHealthyState, PROBE_STATES } from '../services/fleet-console/src/probe.js';
import { scoreRepo, summarise, gradeFor } from '../services/fleet-console/src/score.js';
import { advertisedPackages, __testables as registryInternals } from '../services/fleet-console/src/registry.js';
import { badgeSvg, repoBadge, deploymentBadge, fleetBadge } from '../services/fleet-console/src/badge.js';
import { esc, ago } from '../services/fleet-console/src/views/html.js';
import { attention, slim } from '../services/fleet-console/src/server.js';
import { mapPool } from '../services/fleet-console/src/pool.js';
const probe = (url, state, extra = {}) => ({ url, state, status: state === 'live' ? 200 : 404, ms: 12, finalUrl: url, redirected: false, detail: '', ...extra });
const baseRepo = {
name: 'widget',
description: 'A widget',
stars: 10,
topics: ['a', 'b', 'c'],
license: 'MIT',
pushedAt: new Date(Date.now() - 5 * 86400000).toISOString(),
readmeBytes: 4000,
hasDocsDir: true,
deployments: [],
links: [],
packages: { checked: [], missing: [] }
};
describe('README link extraction', () => {
it('pulls markdown, reference, HTML and bare links while skipping images', () => {
const readme = `
# Widget
[Live demo](https://widget.example.dev/) and 
<a href="https://docs.widget.dev">Docs site</a>
See https://spec.example.org/v1 for the format.
[ref]: https://ref.example.net/page
`;
const urls = extractReadmeLinks(readme).map((link) => link.url);
expect(urls).toContain('https://widget.example.dev/');
expect(urls).toContain('https://docs.widget.dev/');
expect(urls).toContain('https://spec.example.org/v1');
expect(urls).toContain('https://ref.example.net/page');
expect(urls.some((url) => url.includes('shields.io'))).toBe(false);
});
it('ignores URLs inside fenced code blocks', () => {
const readme = ['```bash', 'curl https://api.internal-only.test/v1/thing', '```', '[real](https://real.example.dev)'].join('\n');
const urls = extractReadmeLinks(readme).map((link) => link.url);
expect(urls).toEqual(['https://real.example.dev/']);
});
it('strips trailing punctuation from bare URLs', () => {
const urls = extractReadmeLinks('Visit https://example.dev/page, then leave.').map((link) => link.url);
expect(urls).toEqual(['https://example.dev/page']);
});
it('treats github, npm and badge hosts as not worth checking', () => {
expect(isIgnoredHost('https://github.com/a/b')).toBe(true);
expect(isIgnoredHost('https://www.npmjs.com/package/x')).toBe(true);
expect(isIgnoredHost('https://img.shields.io/badge.svg')).toBe(true);
expect(isIgnoredHost('https://widget.example.dev')).toBe(false);
});
it('rejects non-http schemes and unparseable values', () => {
const urls = extractReadmeLinks('[mail](mailto:[email protected]) [js](javascript:alert(1)) [ok](https://ok.example.dev)').map((link) => link.url);
expect(urls).toEqual(['https://ok.example.dev/']);
});
});
describe('deployment claim detection', () => {
const call = (overrides) =>
deploymentCandidates({ repoName: 'widget', homepage: '', pagesUrl: '', manifestHomepage: '', links: [], ...overrides }).map((entry) => entry.url);
it('counts the homepage field, Pages URL and manifest homepage', () => {
const urls = call({ homepage: 'https://widget.dev', pagesUrl: 'https://owner.github.io/widget/', manifestHomepage: 'https://manifest.example.dev' });
expect(urls.sort()).toEqual(['https://manifest.example.dev/', 'https://owner.github.io/widget/', 'https://widget.dev/']);
});
it('counts known hosting providers found in the README', () => {
const urls = call({ links: [{ url: 'https://thing-abc.a.run.app/', label: 'API', source: 'markdown' }] });
expect(urls).toEqual(['https://thing-abc.a.run.app/']);
});
it('counts a link labelled as live but not an ordinary reference', () => {
const urls = call({
links: [
{ url: 'https://try.example.dev/', label: 'Live demo', source: 'markdown' },
{ url: 'https://spec.example.org/', label: 'the specification', source: 'markdown' }
]
});
expect(urls).toEqual(['https://try.example.dev/']);
});
it('does not claim a third party site because its link text contains the word live', () => {
// A README linking "Debian live-build" is not promising to run debian.org.
const urls = call({
homepage: 'https://widget.dev',
links: [{ url: 'https://live-team.pages.debian.net/live-manual/', label: 'Debian live-build', source: 'markdown' }]
});
expect(urls).toEqual(['https://widget.dev/']);
});
it('collapses many paths on one host into a small sample of that one site', () => {
const links = Array.from({ length: 40 }, (unused, index) => ({ url: `https://widget.dev/page-${index}`, label: '', source: 'markdown' }));
const urls = call({ homepage: 'https://widget.dev', links });
// One site, one deployment claim, plus a couple of deeper paths as a spot check.
expect(urls.length).toBe(3);
expect(urls[0]).toBe('https://widget.dev/');
});
it('caps the total number of probes even across many hosts', () => {
const links = Array.from({ length: 30 }, (unused, index) => ({ url: `https://host-${index}.pages.dev/`, label: '', source: 'markdown' }));
expect(call({ links }).length).toBeLessThanOrEqual(8);
});
it('never invents an origin root that was not claimed', () => {
// On a project Pages site the origin root is a different repository's page.
const urls = call({ pagesUrl: 'https://owner.github.io/widget/' });
expect(urls).toEqual(['https://owner.github.io/widget/']);
});
it('recovers a real URL from trailing markdown noise instead of probing the noise', () => {
const urls = call({ links: [{ url: 'https://owner.github.io/widget/**', label: '', source: 'bare' }] });
expect(urls).toEqual(['https://owner.github.io/widget/']);
});
it('drops template placeholders and interior globs rather than probing them', () => {
const urls = call({
links: [
{ url: 'https://api.example.dev/${version}/thing', label: 'Live demo', source: 'markdown' },
{ url: 'https://cdn.example.dev/*/asset.js', label: 'Live demo', source: 'markdown' },
{ url: 'https://widget.dev/real', label: 'Live demo', source: 'markdown' }
]
});
expect(urls).toEqual(['https://widget.dev/real']);
});
it('counts a host that spells out the repository name', () => {
const urls = call({ links: [{ url: 'https://widget.example.io/', label: '', source: 'bare' }] });
expect(urls).toEqual(['https://widget.example.io/']);
});
it('does not double count the same URL reached two ways', () => {
const urls = call({ homepage: 'https://widget.dev', links: [{ url: 'https://widget.dev', label: 'Live', source: 'markdown' }] });
expect(urls).toEqual(['https://widget.dev/']);
});
});
describe('probe classification', () => {
const { classifyStatus, classifyError } = probeInternals;
it('separates the ways a request can fail to return a page', () => {
expect(classifyStatus(200, false)).toBe('live');
expect(classifyStatus(200, true)).toBe('redirected');
expect(classifyStatus(402, false)).toBe('payment_required');
expect(classifyStatus(401, false)).toBe('auth_required');
expect(classifyStatus(403, false)).toBe('auth_required');
expect(classifyStatus(429, false)).toBe('rate_limited');
expect(classifyStatus(404, false)).toBe('not_found');
expect(classifyStatus(410, false)).toBe('not_found');
expect(classifyStatus(503, false)).toBe('server_error');
});
it('maps transport failures to their cause', () => {
expect(classifyError({ cause: { code: 'ENOTFOUND' } })).toBe('dns_failure');
expect(classifyError({ cause: { code: 'ECONNREFUSED' } })).toBe('refused');
expect(classifyError({ cause: { code: 'CERT_HAS_EXPIRED' } })).toBe('tls_failure');
expect(classifyError({ name: 'AbortError', message: 'aborted' })).toBe('timeout');
expect(classifyError(new Error('something else'))).toBe('unreachable');
});
it('treats only live and redirected as healthy', () => {
expect(isHealthyState('live')).toBe(true);
expect(isHealthyState('redirected')).toBe(true);
expect(isHealthyState('payment_required')).toBe(false);
});
it('has a label and tone for every state the classifiers can produce', () => {
for (const state of ['live', 'redirected', 'payment_required', 'auth_required', 'rate_limited', 'not_found', 'server_error', 'dns_failure', 'refused', 'tls_failure', 'timeout', 'unreachable']) {
expect(PROBE_STATES[state], state).toBeTruthy();
}
});
});
describe('scoring', () => {
it('gives a fully healthy repository a top grade', () => {
const { score, grade } = scoreRepo({
...baseRepo,
deployments: [probe('https://widget.dev/', 'live')],
links: [probe('https://spec.example.org/', 'live')],
packages: { checked: [{ name: 'widget', published: true, latest: '1.2.0', deprecated: false, role: 'manifest' }], missing: [], ownPackage: { name: 'widget', published: true, latest: '1.2.0' } },
packageVersion: '1.2.0'
});
expect(score).toBe(100);
expect(grade.grade).toBe('A');
});
it('does not punish a library for having nothing deployed', () => {
const withoutDeployment = scoreRepo(baseRepo);
const deploymentCheck = withoutDeployment.checks.find((check) => check.id === 'deployment');
expect(deploymentCheck.status).toBe('skip');
// A skipped check leaves the denominator entirely, so the rest still scores full marks.
expect(withoutDeployment.score).toBe(100);
});
it('fails a repository whose only advertised deployment is down', () => {
const { score, checks } = scoreRepo({ ...baseRepo, deployments: [probe('https://gone.example.dev/', 'payment_required')] });
expect(checks.find((check) => check.id === 'deployment').status).toBe('fail');
expect(score).toBeLessThan(100);
});
it('warns when some but not all deployments respond', () => {
const { checks } = scoreRepo({ ...baseRepo, deployments: [probe('https://a.example.dev/', 'live'), probe('https://b.example.dev/', 'not_found')] });
expect(checks.find((check) => check.id === 'deployment').status).toBe('warn');
});
it('fails a repository advertising a package that was never published', () => {
const { checks } = scoreRepo({
...baseRepo,
packages: { checked: [{ name: 'ghost-package', published: false, latest: '', deprecated: false, role: 'readme' }], missing: ['ghost-package'] }
});
const check = checks.find((entry) => entry.id === 'packages');
expect(check.status).toBe('fail');
expect(check.evidence).toContain('ghost-package');
expect(check.fix).toBeTruthy();
});
it('does not count an auth wall or a rate limit as a dead link', () => {
const { checks } = scoreRepo({ ...baseRepo, links: [probe('https://private.example.dev/', 'auth_required'), probe('https://slow.example.dev/', 'rate_limited')] });
expect(checks.find((check) => check.id === 'links').status).toBe('pass');
});
it('warns when the published version has drifted from the manifest', () => {
const { checks } = scoreRepo({
...baseRepo,
packages: { checked: [{ name: 'widget', published: true, latest: '1.0.0', deprecated: false, role: 'manifest' }], missing: [], ownPackage: { name: 'widget', published: true, latest: '1.0.0' } },
packageVersion: '2.0.0'
});
const check = checks.find((entry) => entry.id === 'release-sync');
expect(check.status).toBe('warn');
expect(check.evidence).toContain('2.0.0');
});
it('degrades a stale, undocumented, unlicensed repository', () => {
const { score, grade } = scoreRepo({
...baseRepo,
description: '',
license: '',
topics: [],
readmeBytes: 0,
hasDocsDir: false,
pushedAt: new Date(Date.now() - 900 * 86400000).toISOString()
});
expect(score).toBeLessThan(40);
expect(grade.grade).toBe('F');
});
it('maps scores onto grade bands at the boundaries', () => {
expect(gradeFor(100).grade).toBe('A');
expect(gradeFor(90).grade).toBe('A');
expect(gradeFor(89).grade).toBe('B');
expect(gradeFor(75).grade).toBe('B');
expect(gradeFor(60).grade).toBe('C');
expect(gradeFor(40).grade).toBe('D');
expect(gradeFor(0).grade).toBe('F');
});
it('never returns a score outside 0..100', () => {
for (const repo of [baseRepo, { ...baseRepo, description: '', license: '', topics: [], readmeBytes: 0, hasDocsDir: false }]) {
const { score } = scoreRepo(repo);
expect(score).toBeGreaterThanOrEqual(0);
expect(score).toBeLessThanOrEqual(100);
}
});
});
describe('fleet summary', () => {
it('rolls up scores, deployments, links and missing packages', () => {
const repos = [
{ ...baseRepo, name: 'a', score: 100, grade: gradeFor(100), stars: 5, deployments: [probe('https://a.dev/', 'live')], links: [], packages: { checked: [], missing: [] } },
{ ...baseRepo, name: 'b', score: 50, grade: gradeFor(50), stars: 3, deployments: [probe('https://b.dev/', 'not_found')], links: [probe('https://x.dev/', 'dns_failure')], packages: { checked: [], missing: ['ghost'] } }
];
const summary = summarise(repos);
expect(summary.repos).toBe(2);
expect(summary.stars).toBe(8);
expect(summary.medianScore).toBe(75);
expect(summary.deployments).toMatchObject({ total: 2, healthy: 1 });
expect(summary.links).toMatchObject({ total: 1, dead: 1 });
expect(summary.missingPackages).toEqual([{ repo: 'b', name: 'ghost' }]);
expect(summary.byGrade.A).toBe(1);
});
it('handles an empty fleet without dividing by zero', () => {
const summary = summarise([]);
expect(summary.medianScore).toBe(0);
expect(summary.averageScore).toBe(0);
expect(summary.repos).toBe(0);
});
});
describe('npm registry parsing', () => {
it('finds package names across npm, yarn, pnpm and bun install lines', () => {
const readme = `
\`npm install @scope/thing\`
yarn add other-thing@^2.0.0
pnpm add -D dev-thing
bun add third-thing
`;
expect(advertisedPackages(readme).sort()).toEqual(['@scope/thing', 'dev-thing', 'other-thing', 'third-thing']);
});
it('skips flags, local paths, tarballs and git specifiers', () => {
const names = advertisedPackages('npm install -g ./local-dir ../other https://x.test/a.tgz github:owner/repo real-package');
expect(names).toEqual(['real-package']);
});
it('does not mistake a port number on an install line for a package', () => {
expect(advertisedPackages('npm install serve 3001')).toEqual(['serve']);
});
it('strips a version range without eating a scope', () => {
expect(registryInternals.stripVersionRange('@scope/[email protected]')).toBe('@scope/thing');
expect(registryInternals.stripVersionRange('thing@^1.0.0')).toBe('thing');
expect(registryInternals.stripVersionRange('@scope/thing')).toBe('@scope/thing');
});
it('rejects names the registry could never hold', () => {
expect(registryInternals.PACKAGE_NAME.test('Valid-Name')).toBe(false);
expect(registryInternals.PACKAGE_NAME.test('valid-name')).toBe(true);
expect(registryInternals.PACKAGE_NAME.test('@scope/valid')).toBe(true);
});
});
describe('badges', () => {
it('renders valid, self-describing SVG', () => {
const svg = badgeSvg({ label: 'fleet health', message: '92/100 A', tone: 'good' });
expect(svg.startsWith('<svg')).toBe(true);
expect(svg).toContain('role="img"');
expect(svg).toContain('aria-label="fleet health: 92/100 A"');
expect(svg.trim().endsWith('</svg>')).toBe(true);
});
it('escapes text so a repository name can never break the markup', () => {
expect(badgeSvg({ label: 'a<b>', message: '"x"&y', tone: 'bad' })).toContain('a<b>');
});
it('reports an unknown repository rather than inventing a score', () => {
expect(repoBadge(null)).toContain('unknown');
expect(fleetBadge(null)).toContain('not scanned');
});
it('summarises deployment health', () => {
expect(deploymentBadge({ deployments: [probe('https://a.dev/', 'live'), probe('https://b.dev/', 'not_found')] })).toContain('1/2 live');
expect(deploymentBadge({ deployments: [] })).toContain('none advertised');
});
it('scales the badge width with its text', () => {
const narrow = badgeSvg({ label: 'a', message: 'b', tone: 'good' });
const wide = badgeSvg({ label: 'a much longer label', message: 'and a longer message', tone: 'good' });
const width = (svg) => Number(svg.match(/width="(\d+)"/)[1]);
expect(width(wide)).toBeGreaterThan(width(narrow));
});
});
describe('attention feed', () => {
const snapshot = {
owner: 'someone',
generatedAt: '2026-01-01T00:00:00.000Z',
repos: [
{
...baseRepo,
name: 'alpha',
htmlUrl: 'https://github.com/someone/alpha',
deployments: [probe('https://alpha.dev/', 'payment_required')],
links: [probe('https://dead.example.dev/', 'dns_failure')],
packages: { checked: [], missing: ['ghost-pkg'] },
checks: [{ id: 'license', title: 'Declares a license', weight: 6, status: 'fail', evidence: 'none', fix: 'Add a LICENSE file.' }]
}
]
};
it('ranks broken deployments and unpublished packages above dead links', () => {
const report = attention(snapshot);
expect(report.count).toBe(4);
expect(report.items[0].severity).toBe('high');
expect(report.items.at(-1).kind).toBe('dead_link');
expect(report.items.map((item) => item.kind)).toContain('package_unpublished');
expect(report.items.map((item) => item.kind)).toContain('check_failed:license');
});
it('slims a repository down to what a list view needs', () => {
const record = slim(snapshot.repos[0]);
expect(record).toMatchObject({ name: 'alpha', unpublishedPackages: ['ghost-pkg'] });
expect(record.broken).toEqual([{ url: 'https://alpha.dev/', state: 'payment_required' }]);
expect(record.live).toEqual([]);
});
});
describe('view helpers', () => {
it('escapes every character that could close a tag or an attribute', () => {
expect(esc('<script>"x"&\'y\'</script>')).toBe('<script>"x"&'y'</script>');
});
it('renders relative times in plain language', () => {
expect(ago(new Date(Date.now() - 30 * 1000).toISOString())).toMatch(/second/);
expect(ago(new Date(Date.now() - 3 * 86400000).toISOString())).toBe('3 days ago');
expect(ago('')).toBe('never');
expect(ago('not a date')).toBe('never');
});
});
describe('bounded concurrency', () => {
it('preserves input order and never exceeds the limit', async () => {
let active = 0;
let peak = 0;
const result = await mapPool([1, 2, 3, 4, 5, 6, 7, 8], 3, async (value) => {
active += 1;
peak = Math.max(peak, active);
await new Promise((resolve) => setTimeout(resolve, 5));
active -= 1;
return value * 2;
});
expect(result).toEqual([2, 4, 6, 8, 10, 12, 14, 16]);
expect(peak).toBeLessThanOrEqual(3);
});
it('handles an empty list', async () => {
expect(await mapPool([], 4, async () => 1)).toEqual([]);
});
});