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, vi } from 'vitest';
import {
parseHuggingfaceLoraRef,
buildHfResolveUrl,
buildHfAuthHeaders,
pickHfLoraFile,
detectVideoLoraFamily,
detectImageLoraFamily,
detectHfLoraFamily,
flux2VariantFromBlob,
buildHfLoraSidecar,
fetchHuggingfaceModel,
searchHuggingfaceLoraModels,
} from './huggingfaceLora.js';
import { RUNNER_FAMILIES, VIDEO_LORA_FAMILIES } from './runners.js';
describe('parseHuggingfaceLoraRef', () => {
it('parses a full HF URL', () => {
expect(parseHuggingfaceLoraRef('https://huggingface.co/fal/ltx2.3-audio-reactive-lora'))
.toEqual({ repo: 'fal/ltx2.3-audio-reactive-lora', revision: null, file: null });
});
it('recovers a revision from /tree/<rev> and /blob/<rev> URLs', () => {
expect(parseHuggingfaceLoraRef('https://huggingface.co/fal/x/tree/v1.0'))
.toEqual({ repo: 'fal/x', revision: 'v1.0', file: null });
expect(parseHuggingfaceLoraRef('https://huggingface.co/fal/x/blob/main/lora.safetensors'))
.toEqual({ repo: 'fal/x', revision: 'main', file: 'lora.safetensors' });
});
it('takes only the first segment after tree/blob as the revision (subpaths are not part of the ref)', () => {
// The common copy-paste case: a single-segment revision followed by a
// (possibly nested) subpath. Only `main` is the ref; the rest is the path.
expect(parseHuggingfaceLoraRef('https://huggingface.co/fal/x/blob/main/weights/lora.safetensors'))
.toEqual({ repo: 'fal/x', revision: 'main', file: 'weights/lora.safetensors' });
expect(parseHuggingfaceLoraRef('https://huggingface.co/fal/x/tree/main/subdir'))
.toEqual({ repo: 'fal/x', revision: 'main', file: null });
});
it('recovers a .safetensors path from a /resolve/<rev>/… URL', () => {
expect(parseHuggingfaceLoraRef(
'https://huggingface.co/Alissonerdx/CharacterSheet/resolve/main/TripleView_klein9b_v1.safetensors',
)).toEqual({
repo: 'Alissonerdx/CharacterSheet',
revision: 'main',
file: 'TripleView_klein9b_v1.safetensors',
});
});
it('recovers a slash-containing ref from the org/name@rev form (URL form is ambiguous)', () => {
expect(parseHuggingfaceLoraRef('fal/x@refs/pr/123'))
.toEqual({ repo: 'fal/x', revision: 'refs/pr/123', file: null });
});
it('parses a bare org/name id (optionally @rev or :rev)', () => {
expect(parseHuggingfaceLoraRef('fal/ltx-lora')).toEqual({ repo: 'fal/ltx-lora', revision: null, file: null });
expect(parseHuggingfaceLoraRef('fal/ltx-lora@v2')).toEqual({ repo: 'fal/ltx-lora', revision: 'v2', file: null });
expect(parseHuggingfaceLoraRef('fal/ltx-lora:abc123')).toEqual({ repo: 'fal/ltx-lora', revision: 'abc123', file: null });
});
it('rejects garbage and non-HF hosts', () => {
expect(() => parseHuggingfaceLoraRef('')).toThrow(/Empty/);
expect(() => parseHuggingfaceLoraRef('https://example.com/fal/x')).toThrow(/Not a HuggingFace/);
expect(() => parseHuggingfaceLoraRef('justaword')).toThrow(/org\/name/);
});
});
describe('buildHfResolveUrl', () => {
it('builds a resolve URL defaulting revision to main and encoding path segments', () => {
expect(buildHfResolveUrl('fal/x', null, 'lora.safetensors'))
.toBe('https://huggingface.co/fal/x/resolve/main/lora.safetensors');
expect(buildHfResolveUrl('fal/x', 'v1', 'sub dir/lora.safetensors'))
.toBe('https://huggingface.co/fal/x/resolve/v1/sub%20dir/lora.safetensors');
});
});
describe('buildHfAuthHeaders', () => {
it('returns a bearer header only when a token is present', () => {
expect(buildHfAuthHeaders('hf_abc')).toEqual({ Authorization: 'Bearer hf_abc' });
expect(buildHfAuthHeaders('')).toEqual({});
expect(buildHfAuthHeaders(undefined)).toEqual({});
});
});
describe('pickHfLoraFile', () => {
const m = (...names) => ({ siblings: names.map((rfilename) => ({ rfilename })) });
it('returns the lone .safetensors', () => {
expect(pickHfLoraFile(m('lora.safetensors', 'README.md'))).toBe('lora.safetensors');
});
it('prefers the canonical diffusers filename', () => {
expect(pickHfLoraFile(m('extra.safetensors', 'pytorch_lora_weights.safetensors')))
.toBe('pytorch_lora_weights.safetensors');
});
it('prefers a name containing "lora" when no canonical match', () => {
expect(pickHfLoraFile(m('model.safetensors', 'my_style_lora.safetensors')))
.toBe('my_style_lora.safetensors');
});
it('selects an exact versioned file when requested', () => {
const model = {
id: 'fal/audio-reactive',
...m('audio_reactive.safetensors', 'audio_reactive_v2.safetensors'),
};
expect(pickHfLoraFile(model, 'audio_reactive_v2.safetensors'))
.toBe('audio_reactive_v2.safetensors');
expect(() => pickHfLoraFile(model, 'audio_reactive_v3.safetensors'))
.toThrow(/does not contain audio_reactive_v3/);
});
it('throws when there is no .safetensors', () => {
expect(() => pickHfLoraFile(m('config.json', 'README.md'))).toThrow(/no .safetensors/);
});
it('prefers a Flux.2 Klein 9B sibling over a Krea sibling when hinted', () => {
const model = m(
'DynamicCharacterSheet_krea2_v1.safetensors',
'QuadView_klein9b_v1.safetensors',
'QuadView_krea2_v1.safetensors',
'TripleView_klein9b_v1.safetensors',
);
expect(pickHfLoraFile(model, null, { family: RUNNER_FAMILIES.FLUX2, fluxVariant: '9b' }))
.toBe('QuadView_klein9b_v1.safetensors');
});
});
describe('detectVideoLoraFamily', () => {
it('classifies LTX repos as ltx-video from the repo id', () => {
expect(detectVideoLoraFamily({ repo: 'fal/ltx2.3-audio-reactive-lora' })).toBe(VIDEO_LORA_FAMILIES.LTX_VIDEO);
expect(detectVideoLoraFamily({ repo: 'Lightricks/LTX-Video-LoRA' })).toBe(VIDEO_LORA_FAMILIES.LTX_VIDEO);
});
it('classifies via tags / base_model when the id is opaque', () => {
expect(detectVideoLoraFamily({ repo: 'someone/cool-lora', model: { tags: ['ltxv', 'lora'] } }))
.toBe(VIDEO_LORA_FAMILIES.LTX_VIDEO);
expect(detectVideoLoraFamily({ repo: 'someone/cool-lora', model: { cardData: { base_model: 'Lightricks/LTX-Video' } } }))
.toBe(VIDEO_LORA_FAMILIES.LTX_VIDEO);
});
it('classifies MiniMax H3 repos as minimax-h3', () => {
expect(detectVideoLoraFamily({ repo: 'someone/minimax-h3-character-lora' })).toBe(VIDEO_LORA_FAMILIES.MINIMAX_H3);
expect(detectVideoLoraFamily({ repo: 'someone/opaque', model: { cardData: { base_model: 'MiniMaxAI/MiniMax-H3' } } }))
.toBe(VIDEO_LORA_FAMILIES.MINIMAX_H3);
expect(detectVideoLoraFamily({ repo: 'someone/opaque', model: { tags: ['minimax h3', 'lora'] } }))
.toBe(VIDEO_LORA_FAMILIES.MINIMAX_H3);
});
it('needs the minimax maker token — a bare "h3" version suffix must not mis-tag', () => {
expect(detectVideoLoraFamily({ repo: 'someone/style-h3' })).toBe(null);
expect(detectVideoLoraFamily({ repo: 'someone/h3-anime-lora', model: { tags: ['sdxl'] } })).toBe(null);
});
it('prefers H3 over LTX when an H3 card also name-drops LTX', () => {
expect(detectVideoLoraFamily({
repo: 'someone/minimax-h3-lora',
model: { cardData: { base_model: 'MiniMaxAI/MiniMax-H3' }, tags: ['ltx-video'] },
})).toBe(VIDEO_LORA_FAMILIES.MINIMAX_H3);
});
it('returns null for unrelated repos (e.g. an image SDXL LoRA)', () => {
expect(detectVideoLoraFamily({ repo: 'someone/sdxl-anime-lora', model: { tags: ['sdxl'] } })).toBe(null);
});
});
describe('flux2VariantFromBlob', () => {
it('reads klein9b / klein-9b / flux.2-klein-9b', () => {
expect(flux2VariantFromBlob('flux.2-klein-9b')).toBe('9b');
expect(flux2VariantFromBlob('TripleView_klein9b_v1.safetensors')).toBe('9b');
expect(flux2VariantFromBlob('flux2-klein-4b-int8')).toBe('4b');
});
it('does not treat 4bit as a size variant', () => {
expect(flux2VariantFromBlob('model-4bit')).toBe(null);
});
});
describe('detectImageLoraFamily', () => {
const characterSheet = {
tags: ['lora', 'flux.2', 'flux.2-klein-9b', 'krea-2'],
siblings: [
{ rfilename: 'DynamicCharacterSheet_krea2_v1.safetensors' },
{ rfilename: 'QuadView_klein9b_v1.safetensors' },
{ rfilename: 'QuadView_krea2_v1.safetensors' },
{ rfilename: 'TripleView_klein9b_v1.safetensors' },
],
};
it('classifies Alissonerdx/CharacterSheet as flux2-9b from tags + filenames', () => {
expect(detectImageLoraFamily({ repo: 'Alissonerdx/CharacterSheet', model: characterSheet }))
.toEqual({ family: RUNNER_FAMILIES.FLUX2, fluxVariant: '9b' });
});
it('does not inherit repo flux.2 tags onto a picked Krea sibling', () => {
expect(detectImageLoraFamily({
repo: 'Alissonerdx/CharacterSheet',
model: characterSheet,
file: 'QuadView_krea2_v1.safetensors',
})).toBe(null);
});
it('classifies a klein9b filename even without flux tags', () => {
expect(detectImageLoraFamily({
repo: 'someone/opaque-sheet',
model: { tags: ['lora'], siblings: [{ rfilename: 'TripleView_klein9b_v1.safetensors' }] },
})).toEqual({ family: RUNNER_FAMILIES.FLUX2, fluxVariant: '9b' });
});
});
describe('detectHfLoraFamily', () => {
it('prefers Flux.2 over LTX when a card name-drops LTX as a use case', () => {
expect(detectHfLoraFamily({
repo: 'Alissonerdx/CharacterSheet',
model: {
tags: ['lora', 'flux.2-klein-9b'],
siblings: [{ rfilename: 'TripleView_klein9b_v1.safetensors' }],
},
})).toEqual({ family: RUNNER_FAMILIES.FLUX2, fluxVariant: '9b' });
});
it('still classifies a pure LTX video repo as ltx-video', () => {
expect(detectHfLoraFamily({ repo: 'fal/ltx2.3-audio-reactive-lora' }))
.toEqual({ family: VIDEO_LORA_FAMILIES.LTX_VIDEO, fluxVariant: null });
});
it('returns null for an unsupported image family (SDXL)', () => {
expect(detectHfLoraFamily({ repo: 'someone/sdxl-anime-lora', model: { tags: ['sdxl'] } })).toBe(null);
});
});
describe('buildHfLoraSidecar', () => {
it('shapes a video-LoRA sidecar with a huggingface block and stamped family', () => {
const sidecar = buildHfLoraSidecar({
repo: 'fal/ltx2.3-audio-reactive-lora',
revision: null,
file: 'lora.safetensors',
family: VIDEO_LORA_FAMILIES.LTX_VIDEO,
filename: 'lora-fal-ltx2-3-audio-reactive-lora-hf.safetensors',
model: { tags: ['ltxv'], cardData: { base_model: 'Lightricks/LTX-2.3', instance_prompt: 'audio reactive' } },
});
expect(sidecar.runnerFamily).toBe('ltx-video');
expect(sidecar.source).toBe('huggingface');
expect(sidecar.huggingface.repo).toBe('fal/ltx2.3-audio-reactive-lora');
expect(sidecar.huggingface.revision).toBe('main');
expect(sidecar.huggingface.baseModel).toBe('Lightricks/LTX-2.3');
expect(sidecar.triggerWords).toEqual(['audio reactive']);
expect(sidecar.recommendedScale).toBe(1.0);
expect(sidecar.civitai).toBeUndefined();
expect(sidecar.file.downloadUrl).toContain('/resolve/main/lora.safetensors');
expect(sidecar.license).toBeNull();
});
it('persists a HuggingFace card license when the model reports one', () => {
const sidecar = buildHfLoraSidecar({
repo: 'org/weights',
revision: null,
file: 'lora.safetensors',
family: VIDEO_LORA_FAMILIES.LTX_VIDEO,
filename: 'lora-org-weights-hf.safetensors',
model: { cardData: { license: 'apache-2.0' }, tags: ['ltxv'] },
});
expect(sidecar.license).toBe('apache-2.0');
});
it('labels a V2 LoRA distinctly and uses its recommended scale', () => {
const sidecar = buildHfLoraSidecar({
repo: 'fal/ltx2.3-audio-reactive-lora',
revision: null,
file: 'ltx2.3_audio_reactive_lora_v2.safetensors',
family: VIDEO_LORA_FAMILIES.LTX_VIDEO,
filename: 'lora-fal-ltx2.3-audio-reactive-lora-v2-hf.safetensors',
model: {},
});
expect(sidecar.name).toBe('ltx2.3-audio-reactive-lora · ltx2.3_audio_reactive_lora_v2');
expect(sidecar.recommendedScale).toBe(1.2);
});
it('stamps fluxVariant and a file-stem name for a Flux.2 Klein collection', () => {
const sidecar = buildHfLoraSidecar({
repo: 'Alissonerdx/CharacterSheet',
revision: null,
file: 'QuadView_klein9b_v1.safetensors',
family: RUNNER_FAMILIES.FLUX2,
fluxVariant: '9b',
filename: 'lora-alissonerdx-charactersheet-quadview-klein9b-v1-hf.safetensors',
model: { tags: ['flux.2-klein-9b'] },
});
expect(sidecar.runnerFamily).toBe('flux2');
expect(sidecar.fluxVariant).toBe('9b');
expect(sidecar.name).toBe('CharacterSheet · QuadView_klein9b_v1');
});
});
describe('fetchHuggingfaceModel', () => {
it('rejects malformed repo ids before any fetch', async () => {
await expect(fetchHuggingfaceModel('notarepo')).rejects.toThrow(/Invalid HuggingFace repo id/);
});
it('surfaces a gated/auth error on 401/403', async () => {
const fetchImpl = async () => ({ ok: false, status: 403 });
await expect(fetchHuggingfaceModel('fal/x', { fetchImpl })).rejects.toMatchObject({ code: 'HF_AUTH' });
});
it('returns the parsed body on success', async () => {
const body = { id: 'fal/x', siblings: [{ rfilename: 'lora.safetensors' }], tags: ['ltxv'] };
// readResponseJson reads res.text() then parses tolerantly.
const fetchImpl = async () => ({ ok: true, text: async () => JSON.stringify(body) });
await expect(fetchHuggingfaceModel('fal/x', { fetchImpl })).resolves.toEqual(body);
});
it('forwards a caller cancellation signal to the metadata fetch', async () => {
const controller = new AbortController();
const fetchImpl = vi.fn(async () => ({ ok: true, text: async () => '{}' }));
await fetchHuggingfaceModel('fal/x', { fetchImpl, signal: controller.signal });
expect(fetchImpl).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ signal: controller.signal }));
});
});
describe('searchHuggingfaceLoraModels', () => {
const listResponse = (items, { link = null } = {}) => ({
ok: true,
text: async () => JSON.stringify(items),
headers: { get: (name) => (name.toLowerCase() === 'link' ? link : null) },
});
it('builds a search+author+filter query and reads the Link "next" header', async () => {
let calledUrl;
const fetchImpl = vi.fn(async (url) => {
calledUrl = url;
return listResponse(
[{ id: 'someorg/some-ltx-lora', tags: ['ltx-video'] }],
{ link: '<https://huggingface.co/api/models?search=vhs&cursor=ABC>; rel="next"' },
);
});
const out = await searchHuggingfaceLoraModels({ query: 'vhs', author: 'someorg', limit: 5, fetchImpl });
const parsed = new URL(calledUrl);
expect(parsed.searchParams.get('search')).toBe('vhs');
expect(parsed.searchParams.get('author')).toBe('someorg');
expect(parsed.searchParams.get('filter')).toBe('lora');
expect(parsed.searchParams.get('limit')).toBe('5');
expect(out.items).toHaveLength(1);
expect(out.nextCursor).toBe('https://huggingface.co/api/models?search=vhs&cursor=ABC');
});
it('returns a null nextCursor when the response carries no Link header', async () => {
const fetchImpl = async () => listResponse([]);
const out = await searchHuggingfaceLoraModels({ query: 'x', fetchImpl });
expect(out.nextCursor).toBeNull();
});
it('fetches the cursor URL directly instead of rebuilding params', async () => {
let calledUrl;
const fetchImpl = vi.fn(async (url) => { calledUrl = url; return listResponse([]); });
await searchHuggingfaceLoraModels({ query: 'ignored', cursor: 'https://huggingface.co/api/models?search=vhs&cursor=ABC', fetchImpl });
expect(calledUrl).toBe('https://huggingface.co/api/models?search=vhs&cursor=ABC');
});
it('rejects a cursor pointing at a non-HuggingFace host', async () => {
const fetchImpl = vi.fn();
await expect(searchHuggingfaceLoraModels({ cursor: 'https://evil.example/api/models', fetchImpl }))
.rejects.toMatchObject({ code: 'HF_BAD_CURSOR' });
expect(fetchImpl).not.toHaveBeenCalled();
});
it('surfaces a non-OK response as HF_SEARCH_FAILED', async () => {
const fetchImpl = async () => ({ ok: false, status: 503 });
await expect(searchHuggingfaceLoraModels({ query: 'x', fetchImpl })).rejects.toMatchObject({ code: 'HF_SEARCH_FAILED' });
});
});