Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
isMtplxRepoId,
parseMtplxPullFrame,
pullMtplxModel,
removeMtplxModel,
searchMtplxCatalog,
} from './mtplxModelManager.js';
import * as bufferedSpawnModule from '../lib/bufferedSpawn.js';
import * as mtplxModels from '../lib/mtplxModels.js';
import * as processEnv from '../lib/processEnv.js';
import * as streamingSpawn from '../lib/streamingSpawn.js';
import * as hfMetadata from './huggingFaceMetadata.js';
import * as huggingfaceLora from '../lib/huggingfaceLora.js';
import * as hfToken from './hfToken.js';
import * as modelManifest from './modelManifest.js';
const BINARY = '/opt/homebrew/bin/mtplx';
const spawnOk = (stdout) => ({ success: true, code: 0, stdout, stderr: '', timedOut: false });
describe('mtplxModelManager', () => {
beforeEach(() => {
vi.restoreAllMocks();
vi.spyOn(processEnv, 'findCommandOnPath').mockReturnValue(BINARY);
vi.spyOn(mtplxModels, 'listMtplxCachedModels').mockResolvedValue({ models: [], error: null });
// Publish dates come from the Hub — no suite may reach it.
vi.spyOn(hfMetadata, 'fetchRepoPublishedDates').mockResolvedValue({});
vi.spyOn(hfToken, 'getHfToken').mockResolvedValue(null);
vi.spyOn(huggingfaceLora, 'fetchHuggingfaceModel').mockResolvedValue({ usedStorage: 0 });
vi.spyOn(console, 'log').mockImplementation(() => {});
vi.spyOn(console, 'error').mockImplementation(() => {});
// The manifest write is real file IO against the install's data root; doubled
// so it can be asserted rather than reaching disk.
vi.spyOn(modelManifest, 'recordModelInstall').mockResolvedValue(true);
vi.spyOn(modelManifest, 'recordModelUninstall').mockResolvedValue(true);
});
describe('isMtplxRepoId', () => {
it('accepts owner/name and rejects anything that could become a flag or a path', () => {
expect(isMtplxRepoId('Example/Qwen-MTP')).toBe(true);
// A leading dash would be read as an option by MTPLX's own argparse, and a
// bare name / URL is not something the search results ever produce.
expect(isMtplxRepoId('-rf')).toBe(false);
expect(isMtplxRepoId('Qwen-MTP')).toBe(false);
expect(isMtplxRepoId('https://huggingface.co/Example/Qwen-MTP')).toBe(false);
expect(isMtplxRepoId('../../etc/passwd')).toBe(false);
// Each segment must START alphanumeric — the same rule the route schema
// enforces, so the two guards cannot drift apart.
expect(isMtplxRepoId('Example/..')).toBe(false);
expect(isMtplxRepoId('Example/-flag')).toBe(false);
});
});
describe('searchMtplxCatalog', () => {
it('maps discover cards and omits --query when nothing was typed', async () => {
const spawn = vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue(spawnOk(JSON.stringify([
{ repo: 'Example/Qwen-MTP', branded_name: 'Qwen MTP', owner: 'Example', downloads: 42, license: 'apache-2.0' },
{ branded_name: 'No repo id — dropped' },
])));
const result = await searchMtplxCatalog({});
expect(result).toEqual({
models: [{ repo: 'Example/Qwen-MTP', name: 'Qwen MTP', owner: 'Example', downloads: 42, license: 'apache-2.0', publishedAt: null }],
error: null,
});
// An empty `--query ''` would search for the empty string instead of
// falling through to upstream's default listing.
expect(spawn.mock.calls[0][1]).not.toContain('--query');
});
it('passes a typed query through as its own argv element', async () => {
const spawn = vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue(spawnOk('[]'));
await searchMtplxCatalog({ query: 'qwen coder', limit: 5 });
const args = spawn.mock.calls[0][1];
expect(args[args.indexOf('--query') + 1]).toBe('qwen coder');
expect(args[args.indexOf('--limit') + 1]).toBe('5');
expect(spawn.mock.calls[0][2]).toMatchObject({ shell: false });
});
it('reports MTPLX\'s own reason rather than an empty list that reads as "none exist"', async () => {
vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue({
success: false, code: 1, stdout: '', stderr: 'error: huggingface.co unreachable', timedOut: false,
});
expect(await searchMtplxCatalog({})).toEqual({ models: [], error: 'error: huggingface.co unreachable' });
});
it("carries each repo's Hub publish date so a card can say how old the checkpoint is", async () => {
vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue(spawnOk(JSON.stringify([
{ repo: 'Example/Qwen-MTP', downloads: 42 },
{ repo: 'Example/Unlisted', downloads: 1 },
])));
hfMetadata.fetchRepoPublishedDates.mockResolvedValue({ 'Example/Qwen-MTP': '2026-01-02T00:00:00.000Z' });
const { models } = await searchMtplxCatalog({});
expect(models[0].publishedAt).toBe('2026-01-02T00:00:00.000Z');
// A repo the Hub has no answer for still lists — the card just omits the age.
expect(models[1].publishedAt).toBeNull();
expect(hfMetadata.fetchRepoPublishedDates).toHaveBeenCalledWith(['Example/Qwen-MTP', 'Example/Unlisted']);
});
it('refuses before spawning when MTPLX is not installed', async () => {
processEnv.findCommandOnPath.mockReturnValue(null);
await expect(searchMtplxCatalog({})).rejects.toThrow(/not found on PATH/);
});
});
describe('parseMtplxPullFrame', () => {
it('normalises a structured progress event', () => {
expect(parseMtplxPullFrame(
JSON.stringify({ event: 'progress', repo_id: 'Example/Qwen-MTP', size_bytes: 10, total_bytes: 100, message: 'Downloading model files' }),
'Example/Qwen-MTP',
)).toEqual({ event: 'progress', model: 'Example/Qwen-MTP', received: 10, total: 100, message: 'Downloading model files' });
});
it('maps `failed` onto the error event the client clears the bar on', () => {
expect(parseMtplxPullFrame(JSON.stringify({ event: 'failed', message: 'pull failed' }), 'Example/A'))
.toMatchObject({ event: 'error', message: 'pull failed' });
});
it('keeps an unparseable line as a message instead of dropping it', () => {
// A download that goes quiet for an hour is indistinguishable from one
// that hung, so a banner line still surfaces.
expect(parseMtplxPullFrame('Bootstrapping with pip...', 'Example/A'))
.toEqual({ event: 'progress', model: 'Example/A', message: 'Bootstrapping with pip...' });
expect(parseMtplxPullFrame(' ', 'Example/A')).toBeNull();
});
it('reports a missing total as null so the bar stays indeterminate, not 0%', () => {
expect(parseMtplxPullFrame(JSON.stringify({ event: 'start', size_bytes: 0, total_bytes: 0 }), 'Example/A'))
.toMatchObject({ received: 0, total: null });
});
});
describe('pullMtplxModel', () => {
it('pulls MTPLX\'s own default when no model is named', async () => {
const run = vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: true });
const frames = [];
const result = await pullMtplxModel({ onProgress: (f) => frames.push(f) });
expect(run.mock.calls[0][1]).toEqual(['pull', '--progress-json']);
expect(result).toMatchObject({ success: true, model: null });
expect(frames.at(-1)).toMatchObject({ event: 'complete' });
});
it('names the requested repo id on the command line', async () => {
const run = vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: true });
await pullMtplxModel({ model: 'Example/Qwen-MTP' });
expect(run.mock.calls[0][1]).toEqual(['pull', 'Example/Qwen-MTP', '--progress-json']);
});
it('rejects a model that is not a repo id before it reaches argv', async () => {
const run = vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: true });
await expect(pullMtplxModel({ model: '--cache-dir=/etc' })).rejects.toThrow(/Hugging Face repo id/);
expect(run).not.toHaveBeenCalled();
});
it('resolves (never throws) with the downloader\'s reason on failure', async () => {
vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: false, error: 'disk full' });
const frames = [];
const result = await pullMtplxModel({ model: 'Example/Qwen-MTP', onProgress: (f) => frames.push(f) });
expect(result).toEqual({ success: false, model: 'Example/Qwen-MTP', error: 'disk full' });
expect(frames.at(-1)).toMatchObject({ event: 'error', message: 'disk full' });
});
it('forwards progress lines but swallows upstream\'s own terminal frames', async () => {
vi.spyOn(streamingSpawn, 'runStreamingCommand').mockImplementation(async (_cmd, _args, onLine) => {
onLine(JSON.stringify({ event: 'progress', size_bytes: 5, total_bytes: 10 }));
// Upstream emits its own `complete`/`result` before the process exits —
// letting those through would tear the bar down early.
onLine(JSON.stringify({ event: 'complete', size_bytes: 10, total_bytes: 10 }));
return { success: true };
});
const frames = [];
await pullMtplxModel({ model: 'Example/Qwen-MTP', onProgress: (f) => frames.push(f) });
expect(frames.filter((f) => f.event === 'complete')).toHaveLength(1);
expect(frames.some((f) => f.event === 'progress' && f.received === 5)).toBe(true);
});
it('reports what actually landed in the cache, not what was asked for', async () => {
vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: true });
mtplxModels.listMtplxCachedModels.mockResolvedValue({
models: [{ repo_id: 'Example/Qwen-MTP' }], error: null,
});
const result = await pullMtplxModel({ model: 'Example/Qwen-MTP' });
expect(result.cachedModels).toEqual(['Example/Qwen-MTP']);
});
});
describe('removeMtplxModel', () => {
it('delegates deletion to `mtplx remove` and reports the freed bytes', async () => {
const spawn = vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue(
spawnOk(JSON.stringify({ repo_id: 'Example/Qwen-MTP', removed: true, size_bytes_removed: 2048 })),
);
const result = await removeMtplxModel('Example/Qwen-MTP');
// Never an unlink of a path PortOS assembled itself — the cache layout is
// upstream's, and guessing it would be a data-loss bug on the first change.
expect(spawn.mock.calls[0][1]).toEqual(['remove', 'Example/Qwen-MTP', '--json']);
expect(result).toEqual({ success: true, model: 'Example/Qwen-MTP', removed: true, bytesFreed: 2048 });
});
it('refuses anything that is not a repo id', async () => {
const spawn = vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue(spawnOk('{}'));
await expect(removeMtplxModel('--cache-dir')).rejects.toThrow(/Hugging Face repo id/);
expect(spawn).not.toHaveBeenCalled();
});
it('reports "not cached" from the JSON payload, not the bare `}` on stdout', async () => {
// `mtplx remove --json` prints its payload to stdout even on exit 1, so a
// last-stdout-line heuristic would surface a closing brace as the reason.
vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue({
success: false,
code: 1,
stdout: JSON.stringify({ repo_id: 'Example/Qwen-MTP', removed: false }, null, 2),
stderr: '',
timedOut: false,
});
const err = await removeMtplxModel('Example/Qwen-MTP').catch((e) => e);
expect(err.status).toBe(404);
expect(err.message).toMatch(/not in MTPLX's cache/);
});
it('surfaces MTPLX\'s stderr when the removal fails', async () => {
vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue({
success: false, code: 1, stdout: '', stderr: 'error: model not cached', timedOut: false,
});
await expect(removeMtplxModel('Example/Qwen-MTP')).rejects.toThrow(/error: model not cached/);
});
});
// MTPLX pulls through huggingface_hub into the standard HF hub cache, so a
// checkpoint it fetches shows up in the Models → Status inventory like any other
// `models--org--name` directory. Recording lives in this manager because BOTH
// entry points reach it — the model-pull route and the readiness checklist's
// default-checkpoint fetch — and neither would have recorded on its own.
describe('model manifest', () => {
it('records a named pull under its HF cache directory', async () => {
vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: true });
await pullMtplxModel({ model: 'Example/Qwen-MTP' });
expect(modelManifest.recordModelInstall).toHaveBeenCalledWith(expect.objectContaining({
id: 'hf:models--Example--Qwen-MTP',
backend: 'huggingface',
action: { type: 'hf-model', dirName: 'models--Example--Qwen-MTP' },
source: 'download',
}));
});
it('records what actually landed when the default checkpoint was pulled by no name', async () => {
vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: true });
mtplxModels.listMtplxCachedModels.mockResolvedValue({
models: [{ repo_id: 'Example/Default-MTP' }], error: null,
});
await pullMtplxModel({});
expect(modelManifest.recordModelInstall).toHaveBeenCalledWith(expect.objectContaining({
id: 'hf:models--Example--Default-MTP',
}));
});
it('records nothing when the pull failed', async () => {
vi.spyOn(streamingSpawn, 'runStreamingCommand').mockResolvedValue({ success: false, error: 'network' });
await pullMtplxModel({ model: 'Example/Qwen-MTP' });
expect(modelManifest.recordModelInstall).not.toHaveBeenCalled();
});
it('clears the entry when a checkpoint is removed', async () => {
vi.spyOn(bufferedSpawnModule, 'bufferedSpawn').mockResolvedValue(spawnOk(JSON.stringify({ removed: true, size_bytes_removed: 10 })));
await removeMtplxModel('Example/Qwen-MTP');
expect(modelManifest.recordModelUninstall).toHaveBeenCalledWith({
backend: 'huggingface',
key: 'models--Example--Qwen-MTP',
});
});
});
});