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, afterEach, vi } from 'vitest';
import { mockJsonResponse } from '../lib/testHelper.js';
import { existsSync, mkdtempSync, rmSync, writeFileSync, readFileSync } from 'fs';
import { createHash } from 'crypto';
import { tmpdir } from 'os';
import { join } from 'path';
// Minimal structurally-valid safetensors blob: 8-byte LE header length + JSON
// header. verifyDownloadedLora (issue #2199) rejects anything that isn't a
// parseable safetensors header, so download fixtures below must be valid.
const validSafetensors = (header = {}) => {
const json = Buffer.from(JSON.stringify(header), 'utf8');
const len = Buffer.alloc(8);
len.writeBigUInt64LE(BigInt(json.length));
return Buffer.concat([len, json]);
};
const sha256Hex = (buf) => createHash('sha256').update(buf).digest('hex');
// Point PATHS.loras at a temp dir for the duration of each test. PATHS is
// computed at module load against process.cwd / __dirname, so the cleanest
// way to swap it is to mock fileUtils for the loras service.
let tmpRoot;
let tmpLoras;
let lorasService;
let _civitaiLib;
let atomicWriteHook;
// Sidecar writes the service has enqueued but not yet finished (#6265).
//
// `listLoras()` heals a stale/absent `keyLayout` (and `fluxVariant`) by firing
// `patchLoraSidecar(...).catch(() => {})` — deliberately fire-and-forget, so
// listing never blocks or fails on a cache write. That promise outlives the
// test that started it — two tests here were observed still holding a queued
// write at teardown — so `afterEach` rm -rf's the temp root while a queued
// read-modify-write is still walking it, and the next `beforeEach` calls
// `vi.resetModules()` with that work in flight. Both races widen under load,
// which matches #6265: the file passes on its own and read two just-written
// sidecars as `{}` inside a contended full-suite shard.
//
// The queue itself is the only complete seam: every heal goes through
// `createKeyedFileWriteQueue()` regardless of which `listLoras()` call site
// started it, and the queued promise covers the whole stat → read → atomicWrite
// cycle (hooking `atomicWrite` would miss a task that has not reached its write
// yet). Wrapping the factory lets `afterEach` await exactly the work the test
// started — a drain, not a sleep or a retry.
const pendingSidecarWrites = new Set();
const drainSidecarWrites = async () => {
while (pendingSidecarWrites.size) await Promise.all([...pendingSidecarWrites]);
};
beforeEach(async () => {
tmpRoot = mkdtempSync(join(tmpdir(), 'portos-loras-test-'));
tmpLoras = join(tmpRoot, 'loras');
pendingSidecarWrites.clear();
vi.resetModules();
vi.doMock('../lib/fileUtils.js', async () => {
const actual = await vi.importActual('../lib/fileUtils.js');
return {
...actual,
// `data` as well as `loras`: a finished install records itself in the model
// manifest (`data/model-manifest.json`), and the test-isolation guard
// refuses that write while the data root still points at the real install.
PATHS: { ...actual.PATHS, data: tmpRoot, loras: tmpLoras },
atomicWrite: (...args) => atomicWriteHook
? atomicWriteHook(actual.atomicWrite, ...args)
: actual.atomicWrite(...args),
};
});
vi.doMock('../lib/fileWriteQueue.js', async () => {
const actual = await vi.importActual('../lib/fileWriteQueue.js');
return {
...actual,
createKeyedFileWriteQueue: (...factoryArgs) => {
const queue = actual.createKeyedFileWriteQueue(...factoryArgs);
return (key, fn) => {
const write = queue(key, fn);
// Track a silenced copy: a rejected sidecar write is a real product
// outcome several tests assert on, and the drain must not re-throw it
// out of `afterEach`.
const tracked = write.catch(() => {});
pendingSidecarWrites.add(tracked);
tracked.finally(() => pendingSidecarWrites.delete(tracked));
return write; // callers still see the real resolve/reject
};
},
};
});
// Stub settings so resolveCivitaiKey doesn't read the real data/settings.json.
vi.doMock('./settings.js', () => ({
getSettings: async () => ({}),
}));
lorasService = await import('./loras.js');
_civitaiLib = await import('../lib/civitai.js');
// Module identity at the read, asserted once per test. Every fixture below
// writes through the raw `tmpLoras` path while the service resolves its own
// `PATHS.loras` out of the mocked module — if those two ever diverge (a
// reused mock instance, a factory that did not re-run), the symptom is a
// silent empty read many tests later, because `readSidecar` collapses "wrong
// directory" into the same `null` it returns for "no sidecar". Fail here,
// naming both paths, instead.
const { PATHS } = await import('../lib/fileUtils.js');
expect(PATHS.loras).toBe(tmpLoras);
});
afterEach(async () => {
// Before removing the tree the writes are aimed at, and before the next
// `beforeEach` resets the module graph out from under them.
await drainSidecarWrites();
atomicWriteHook = null;
vi.doUnmock('../lib/fileUtils.js');
vi.doUnmock('../lib/fileWriteQueue.js');
vi.doUnmock('./settings.js');
rmSync(tmpRoot, { recursive: true, force: true });
});
describe('listLoras', () => {
it('returns an empty list when the loras dir is missing', async () => {
expect(await lorasService.listLoras()).toEqual([]);
});
it('lists .safetensors files and merges sidecar metadata', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-realstagram-v7.safetensors'), 'fake-weights');
await fs.writeFile(join(tmpLoras, 'lora-realstagram-v7.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-realstagram-v7.safetensors',
name: 'RealStagram',
runnerFamily: 'mflux',
triggerWords: ['rstgrm'],
recommendedScale: 0.85,
installedAt: '2026-05-09T00:00:00.000Z',
}));
// A legacy file the user dropped in pre-Civitai (no sidecar).
await fs.writeFile(join(tmpLoras, 'lora-legacy.safetensors'), 'older-weights');
const list = await lorasService.listLoras();
const realstagram = list.find((l) => l.filename === 'lora-realstagram-v7.safetensors');
const legacy = list.find((l) => l.filename === 'lora-legacy.safetensors');
expect(realstagram.name).toBe('RealStagram');
expect(realstagram.runnerFamily).toBe('mflux');
// Non-flux2 LoRAs: compat key is just the runner family.
expect(realstagram.loraCompatKey).toBe('mflux');
expect(realstagram.fluxVariant).toBe(null);
expect(realstagram.triggerWords).toEqual(['rstgrm']);
expect(realstagram.recommendedScale).toBe(0.85);
expect(legacy.name).toBe('legacy');
expect(legacy.runnerFamily).toBe(null);
expect(legacy.loraCompatKey).toBe(null);
expect(legacy.recommendedScale).toBe(1.0);
});
it('reuses cached metadata while the LoRA file mtime is unchanged', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'cached.safetensors'), 'weights');
await fs.writeFile(join(tmpLoras, 'cached.safetensors.metadata.json'), JSON.stringify({
filename: 'cached.safetensors', name: 'Cached', keyLayout: 'comfyui',
}));
const [first] = await lorasService.listLoras();
const [second] = await lorasService.listLoras();
expect(second).toBe(first);
});
it('invalidates cached metadata after a sidecar patch', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'patched.safetensors'), 'weights');
await fs.writeFile(join(tmpLoras, 'patched.safetensors.metadata.json'), JSON.stringify({
filename: 'patched.safetensors', name: 'Before', keyLayout: 'comfyui',
}));
const [before] = await lorasService.listLoras();
await lorasService.patchLoraSidecar('patched.safetensors', { name: 'After' });
const [after] = await lorasService.listLoras();
expect(after).not.toBe(before);
expect(after.name).toBe('After');
});
it('refreshes cached metadata when a sidecar is replaced outside this service', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
const filePath = join(tmpLoras, 'external.safetensors');
const sidecarPath = `${filePath}.metadata.json`;
await fs.writeFile(filePath, 'weights');
await fs.writeFile(sidecarPath, JSON.stringify({
filename: 'external.safetensors', name: 'Before', keyLayout: 'comfyui',
}));
const [before] = await lorasService.listLoras();
await fs.writeFile(sidecarPath, JSON.stringify({
filename: 'external.safetensors', name: 'After', keyLayout: 'comfyui',
}));
const future = new Date(Date.now() + 10_000);
await fs.utimes(sidecarPath, future, future);
const [after] = await lorasService.listLoras();
expect(after).not.toBe(before);
expect(after.name).toBe('After');
});
it('refreshes cached metadata when the LoRA file mtime changes', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
const filePath = join(tmpLoras, 'updated.safetensors');
await fs.writeFile(filePath, 'weights');
await fs.writeFile(`${filePath}.metadata.json`, JSON.stringify({
filename: 'updated.safetensors', name: 'Updated', keyLayout: 'comfyui',
}));
const [before] = await lorasService.listLoras();
await fs.writeFile(filePath, 'larger-weights');
const future = new Date(Date.now() + 10_000);
await fs.utimes(filePath, future, future);
const [after] = await lorasService.listLoras();
expect(after).not.toBe(before);
expect(after.sizeBytes).toBe(Buffer.byteLength('larger-weights'));
});
it('tags a flux2 LoRA size from the Civitai baseModel without reading the header', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
// Garbage file contents — must NOT be read since baseModel carries the size.
await fs.writeFile(join(tmpLoras, 'lora-f2-9b.safetensors'), 'not-a-real-safetensors');
await fs.writeFile(join(tmpLoras, 'lora-f2-9b.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-f2-9b.safetensors',
name: 'Flux2 9B LoRA',
civitai: { baseModel: 'Flux.2 Klein 9B' },
}));
const list = await lorasService.listLoras();
const lora = list.find((l) => l.filename === 'lora-f2-9b.safetensors');
expect(lora.runnerFamily).toBe('flux2');
expect(lora.fluxVariant).toBe('9b');
expect(lora.loraCompatKey).toBe('flux2-9b');
});
it('detects a flux2 LoRA size from the safetensors header when baseModel lacks it', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
// Real header with a 9B-dim transformer tensor (16384 = 4096×4).
const header = {
'transformer.single_transformer_blocks.0.attn.to_out.lora_A.weight': { dtype: 'F16', shape: [32, 16384], data_offsets: [0, 1] },
};
const json = Buffer.from(JSON.stringify(header), 'utf-8');
const len = Buffer.alloc(8);
len.writeBigUInt64LE(BigInt(json.length), 0);
await fs.writeFile(join(tmpLoras, 'lora-selftrained.safetensors'), Buffer.concat([len, json, Buffer.from([0])]));
// baseModel is the bare family — no size — forcing the header read.
await fs.writeFile(join(tmpLoras, 'lora-selftrained.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-selftrained.safetensors',
name: 'Self-trained 9B',
civitai: { baseModel: 'Flux.2 Klein' },
}));
const list = await lorasService.listLoras();
const lora = list.find((l) => l.filename === 'lora-selftrained.safetensors');
expect(lora.runnerFamily).toBe('flux2');
expect(lora.fluxVariant).toBe('9b');
expect(lora.loraCompatKey).toBe('flux2-9b');
});
it('leaves loraCompatKey at bare flux2 when the size is indeterminate', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
// Unreadable header + no size in baseModel → can't determine the variant.
await fs.writeFile(join(tmpLoras, 'lora-f2-unknown.safetensors'), 'garbage');
await fs.writeFile(join(tmpLoras, 'lora-f2-unknown.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-f2-unknown.safetensors',
civitai: { baseModel: 'Flux.2 Klein' },
}));
const list = await lorasService.listLoras();
const lora = list.find((l) => l.filename === 'lora-f2-unknown.safetensors');
expect(lora.runnerFamily).toBe('flux2');
expect(lora.fluxVariant).toBe(null);
expect(lora.loraCompatKey).toBe('flux2');
});
it('returns [] when PATHS.loras is a file, not a directory', async () => {
const fs = await import('fs/promises');
// Write a plain file at the loras path — stat will show isDirectory()=false.
await fs.mkdir(tmpRoot, { recursive: true });
await fs.writeFile(tmpLoras, 'not-a-directory');
expect(await lorasService.listLoras()).toEqual([]);
});
it('survives an unparseable sidecar', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-broken.safetensors'), 'w');
await fs.writeFile(join(tmpLoras, 'lora-broken.safetensors.metadata.json'), '{ this is not json');
const list = await lorasService.listLoras();
expect(list).toHaveLength(1);
expect(list[0].filename).toBe('lora-broken.safetensors');
expect(list[0].runnerFamily).toBe(null);
});
it('re-derives runnerFamily from civitai.baseModel at read time (heals stale sidecars)', async () => {
// Simulates a LoRA whose sidecar was written before baseModelToRunner()
// recognized 'Ernie' — `runnerFamily` was stored as null at install
// time. After the mapping update, listLoras must NOT trust the cached
// null and must re-derive from the still-correct civitai.baseModel
// (otherwise this LoRA leaks into every runner's compat filter).
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-stale-v1.safetensors'), 'w');
await fs.writeFile(join(tmpLoras, 'lora-stale-v1.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-stale-v1.safetensors',
name: 'Stale Ernie LoRA',
runnerFamily: null, // ← stale value from old install
civitai: { baseModel: 'Ernie' }, // ← still-correct baseModel
triggerWords: [],
installedAt: '2026-05-09T00:00:00.000Z',
}));
const list = await lorasService.listLoras();
const stale = list.find((l) => l.filename === 'lora-stale-v1.safetensors');
expect(stale.runnerFamily).toBe('ernie');
});
it('falls back to stored runnerFamily when civitai.baseModel is absent (legacy LoRAs)', async () => {
// User-dropped LoRA pre-Civitai integration: no civitai block at all,
// just whatever runnerFamily someone may have hand-edited in. Read
// path must respect that rather than coerce to null.
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-handcrafted.safetensors'), 'w');
await fs.writeFile(join(tmpLoras, 'lora-handcrafted.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-handcrafted.safetensors',
name: 'Handcrafted',
runnerFamily: 'mflux',
}));
const list = await lorasService.listLoras();
const lora = list.find((l) => l.filename === 'lora-handcrafted.safetensors');
expect(lora.runnerFamily).toBe('mflux');
});
});
// Adapter-effect diagnostic (#4872). listLoras is a PASSIVE read — a library
// page with 40 installed LoRAs must never fan out into 40 Python children — so
// it surfaces only what the explicit probe already measured, and only while
// that measurement still describes the file on disk.
describe('listLoras — cached adapter-effect report', () => {
const report = (over = {}) => ({
probeVersion: 1, status: 'ok', modules: 8, measured: 8, skippedNonFinite: 0,
skippedUnsupported: 0, zeroModules: 0, medianRms: 0.004, maxRms: 0.02,
reason: null, measuredAt: '2026-08-23T00:00:00.000Z', ...over,
});
// The cache key is the file's real size + mtime, so the sidecar has to be
// written from the file that actually landed on disk — `stamp` overrides let a
// test deliberately mismatch one of them.
const writeLora = async (filename, bytes, effectReport, stamp = {}) => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
const path = join(tmpLoras, filename);
await fs.writeFile(path, Buffer.alloc(bytes, 1));
const s = await fs.stat(path);
const sidecar = effectReport
? { effectReport: { ...effectReport, sizeBytes: s.size, mtimeMs: s.mtimeMs, ...stamp } }
: { name: 'Unmeasured' };
await fs.writeFile(join(tmpLoras, `${filename}.metadata.json`), JSON.stringify({ filename, ...sidecar }));
};
it('surfaces a stored report whose size and mtime still match the file', async () => {
await writeLora('measured.safetensors', 512, report());
const [lora] = await lorasService.listLoras();
expect(lora.effectReport).toMatchObject({ status: 'ok', measured: 8, medianRms: 0.004, sizeBytes: 512 });
});
it('reports null when the LoRA was never measured', async () => {
await writeLora('unmeasured.safetensors', 512, null);
const [lora] = await lorasService.listLoras();
expect(lora.effectReport).toBeNull();
});
it('drops a stored report once the file has been replaced under the same name', async () => {
// A different size is a different adapter. Surfacing the old verdict would
// badge a freshly-installed LoRA with the previous file's measurement.
await writeLora('swapped.safetensors', 1024, report(), { sizeBytes: 512 });
const [lora] = await lorasService.listLoras();
expect(lora.effectReport).toBeNull();
});
it('drops a stored report when the file was rewritten at the SAME size', async () => {
await writeLora('rewritten.safetensors', 512, report(), { mtimeMs: 1 });
const [lora] = await lorasService.listLoras();
expect(lora.effectReport).toBeNull();
});
it('drops a stored report written by a different probe version', async () => {
await writeLora('old.safetensors', 512, report({ probeVersion: 99 }));
const [lora] = await lorasService.listLoras();
expect(lora.effectReport).toBeNull();
});
it('normalizes a hand-edited sidecar rather than trusting it', async () => {
await writeLora('edited.safetensors', 512, report({ status: 'catastrophic', medianRms: 'lots', maxRms: null }));
const [lora] = await lorasService.listLoras();
expect(lora.effectReport).toMatchObject({ status: 'unmeasurable', medianRms: null, maxRms: null });
});
it('will not surface a "zero" verdict that no measurement backs', async () => {
// Refusing a render is the one thing a stale/edited sidecar must never be
// able to cause on its own.
await writeLora('bogus-zero.safetensors', 512, report({ status: 'zero', measured: 0, zeroModules: 0 }));
const [lora] = await lorasService.listLoras();
expect(lora.effectReport.status).toBe('unmeasurable');
});
});
describe('deleteLora', () => {
it('removes file + sidecar', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-x.safetensors'), 'w');
await fs.writeFile(join(tmpLoras, 'lora-x.safetensors.metadata.json'), '{}');
await lorasService.deleteLora('lora-x.safetensors');
expect(existsSync(join(tmpLoras, 'lora-x.safetensors'))).toBe(false);
expect(existsSync(join(tmpLoras, 'lora-x.safetensors.metadata.json'))).toBe(false);
});
it('keeps the model when sidecar removal fails', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
const filePath = join(tmpLoras, 'cleanup-fails.safetensors');
const sidecar = `${filePath}.metadata.json`;
await fs.writeFile(filePath, 'weights');
await fs.mkdir(sidecar);
await fs.writeFile(join(sidecar, 'locked'), 'metadata');
await expect(lorasService.deleteLora('cleanup-fails.safetensors')).rejects.toThrow();
expect(existsSync(filePath)).toBe(true);
expect(existsSync(sidecar)).toBe(true);
});
it('invalidates cached metadata before the same filename is reused', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
const filePath = join(tmpLoras, 'reused.safetensors');
await fs.writeFile(filePath, 'old');
await fs.writeFile(`${filePath}.metadata.json`, JSON.stringify({
filename: 'reused.safetensors', name: 'Old', keyLayout: 'comfyui',
}));
const oldStat = await fs.stat(filePath);
expect((await lorasService.listLoras())[0].name).toBe('Old');
await lorasService.deleteLora('reused.safetensors');
await fs.writeFile(filePath, 'new');
await fs.utimes(filePath, oldStat.atime, oldStat.mtime);
await fs.writeFile(`${filePath}.metadata.json`, JSON.stringify({
filename: 'reused.safetensors', name: 'New', keyLayout: 'comfyui',
}));
expect((await lorasService.listLoras())[0].name).toBe('New');
});
it('rejects path traversal', async () => {
await expect(lorasService.deleteLora('../escape.safetensors')).rejects.toThrow(/Invalid LoRA filename/);
await expect(lorasService.deleteLora('foo/bar.safetensors')).rejects.toThrow(/Invalid LoRA filename/);
await expect(lorasService.deleteLora('foo.bin')).rejects.toThrow(/Invalid LoRA filename/);
});
it('404s for missing files', async () => {
await expect(lorasService.deleteLora('lora-missing.safetensors')).rejects.toThrow(/not found/);
});
it('400s with INVALID_LORA_FILE when path is a directory, not a regular file', async () => {
const fs = await import('fs/promises');
// Create a directory whose name ends in .safetensors — exotic but possible.
await fs.mkdir(join(tmpLoras, 'lora-dir.safetensors'), { recursive: true });
const err = await lorasService.deleteLora('lora-dir.safetensors').catch((e) => e);
expect(err.status).toBe(400);
expect(err.code).toBe('INVALID_LORA_FILE');
});
});
describe('getLora', () => {
it('404s when file does not exist', async () => {
await expect(lorasService.getLora('lora-missing.safetensors')).rejects.toThrow(/not found/i);
});
it('404s when file exists but is not a regular .safetensors file (e.g. directory)', async () => {
const fs = await import('fs/promises');
// listLoras filters out non-file entries, so getLora must surface a 404
// rather than returning null.
await fs.mkdir(join(tmpLoras, 'lora-dir.safetensors'), { recursive: true });
const err = await lorasService.getLora('lora-dir.safetensors').catch((e) => e);
expect(err.status).toBe(404);
expect(err.code).toBe('NOT_FOUND');
});
it('returns a full lora entry when the file is valid', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-x.safetensors'), 'w');
const lora = await lorasService.getLora('lora-x.safetensors');
expect(lora.filename).toBe('lora-x.safetensors');
});
});
describe('patchLoraSidecar', () => {
it('creates a sidecar when none exists', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-y.safetensors'), 'w');
const patched = await lorasService.patchLoraSidecar('lora-y.safetensors', { recommendedScale: 0.5, name: 'Custom' });
expect(patched.recommendedScale).toBe(0.5);
expect(patched.name).toBe('Custom');
expect(JSON.parse(readFileSync(join(tmpLoras, 'lora-y.safetensors.metadata.json'), 'utf-8')).name).toBe('Custom');
});
it('does not recreate a sidecar when deletion wins the write queue', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
const filePath = join(tmpLoras, 'delete-race.safetensors');
const sidecar = `${filePath}.metadata.json`;
await fs.writeFile(filePath, 'weights');
let releaseWrite;
let markWriteStarted;
const writeStarted = new Promise((resolve) => { markWriteStarted = resolve; });
const writeReleased = new Promise((resolve) => { releaseWrite = resolve; });
atomicWriteHook = async (atomicWrite, ...args) => {
markWriteStarted();
await writeReleased;
return atomicWrite(...args);
};
const firstPatch = lorasService.patchLoraSidecar('delete-race.safetensors', { name: 'Before delete' });
await writeStarted;
const deletion = lorasService.deleteLora('delete-race.safetensors');
// Capture the rejection AT CREATION, not after the awaits below: this patch is
// queued behind the deletion and rejects as soon as that lands, which is
// before an `await deletion` on the line after it has returned. Attaching the
// handler later leaves a window where the rejection is genuinely unhandled,
// and Node reports it as such — a false failure about the delete path rather
// than about anything this test asserts.
const latePatch = lorasService.patchLoraSidecar('delete-race.safetensors', { name: 'After delete' })
.catch((error) => error);
releaseWrite();
await firstPatch;
await deletion;
const err = await latePatch;
expect(err.status).toBe(404);
expect(err.code).toBe('NOT_FOUND');
expect(existsSync(filePath)).toBe(false);
expect(existsSync(sidecar)).toBe(false);
});
});
// The sidecar is one JSON document with several writers — the manager renaming a
// LoRA, listLoras() healing keyLayout on read, and the effect probe caching its
// measurement. Each patch is a read-modify-write of the WHOLE file, so
// interleaved cycles let the last writer silently drop the other's field.
describe('patchLoraSidecar — concurrent patches', () => {
it('merges every field when two patches race, rather than last-write-wins', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'shared.safetensors'), 'weights');
await fs.writeFile(join(tmpLoras, 'shared.safetensors.metadata.json'), JSON.stringify({
filename: 'shared.safetensors', name: 'Original',
}));
await Promise.all([
lorasService.patchLoraSidecar('shared.safetensors', { name: 'Renamed' }),
lorasService.patchLoraSidecar('shared.safetensors', { effectReport: { status: 'ok', measured: 4 } }),
lorasService.patchLoraSidecar('shared.safetensors', { keyLayout: 'comfyui' }),
]);
const written = JSON.parse(await fs.readFile(join(tmpLoras, 'shared.safetensors.metadata.json'), 'utf-8'));
expect(written.name).toBe('Renamed');
expect(written.keyLayout).toBe('comfyui');
expect(written.effectReport).toMatchObject({ status: 'ok', measured: 4 });
});
it('does not serialize patches to DIFFERENT LoRAs behind each other', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
for (const name of ['a.safetensors', 'b.safetensors']) {
await fs.writeFile(join(tmpLoras, name), 'weights');
}
const [a, b] = await Promise.all([
lorasService.patchLoraSidecar('a.safetensors', { name: 'A' }),
lorasService.patchLoraSidecar('b.safetensors', { name: 'B' }),
]);
expect([a.name, b.name]).toEqual(['A', 'B']);
});
});
describe('installFromCivitai', () => {
// Build a fake Civitai model JSON we can hand to the fetchImpl.
const FAKE_MODEL = {
id: 2600698,
name: 'RealStagram',
description: 'photoreal LoRA',
type: 'LORA',
creator: { username: 'someone' },
tags: ['photo'],
nsfw: false,
modelVersions: [
{
id: 7,
baseModel: 'Flux.1 D',
trainedWords: ['rstgrm'],
settings: { strength: 0.85 },
images: [{ url: 'https://civitai.com/p.jpg', nsfwLevel: 1 }],
files: [
{ name: 'realstagram.safetensors', primary: true, sizeKB: 1024, hashes: { SHA256: 'abc' }, downloadUrl: 'https://civitai.com/api/download/models/7' },
],
},
],
};
it('downloads, writes the file, writes the sidecar', async () => {
const downloadedBytes = validSafetensors();
const calls = [];
const fetchImpl = async (url) => {
calls.push(url);
if (url.startsWith('https://civitai.com/api/v1/models/2600698')) {
return mockJsonResponse(FAKE_MODEL);
}
if (url.startsWith('https://civitai.com/api/download/models/7')) {
// Return a Web ReadableStream so Readable.fromWeb can consume it.
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(downloadedBytes)); c.close(); },
});
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const sidecar = await lorasService.installFromCivitai({ url: 'https://civitai.red/models/2600698/realstagram' }, { fetchImpl });
expect(sidecar.filename).toBe('lora-realstagram-v7.safetensors');
expect(sidecar.civitai.modelId).toBe(2600698);
expect(sidecar.civitai.versionId).toBe(7);
expect(sidecar.runnerFamily).toBe('mflux');
// Flux.1 D is not a flux2 family → no size variant.
expect(sidecar.fluxVariant).toBe(null);
expect(sidecar.triggerWords).toEqual(['rstgrm']);
expect(sidecar.recommendedScale).toBe(0.85);
// File on disk
const installedPath = join(tmpLoras, sidecar.filename);
expect(existsSync(installedPath)).toBe(true);
expect(readFileSync(installedPath)).toEqual(downloadedBytes);
// Sidecar on disk
const sidecarPath = `${installedPath}.metadata.json`;
expect(JSON.parse(readFileSync(sidecarPath, 'utf-8')).civitai.modelId).toBe(2600698);
// Two HTTP calls — metadata + download
expect(calls).toHaveLength(2);
});
it('shares one in-flight install between duplicate model submissions', async () => {
const downloadedBytes = validSafetensors();
let releaseMetadata;
let metadataCalls = 0;
let downloadCalls = 0;
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/2600698')) {
metadataCalls += 1;
return new Promise((resolve) => {
releaseMetadata = () => resolve(mockJsonResponse(FAKE_MODEL));
});
}
if (url.startsWith('https://civitai.com/api/download/models/7')) {
downloadCalls += 1;
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(downloadedBytes)); c.close(); },
});
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const first = lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl });
await vi.waitFor(() => expect(releaseMetadata).toBeTypeOf('function'));
const second = lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl });
releaseMetadata();
const [firstResult, secondResult] = await Promise.all([first, second]);
expect(secondResult).toEqual(firstResult);
expect(metadataCalls).toBe(1);
expect(downloadCalls).toBe(1);
});
it('keeps concurrent installs for different versions of one model independent', async () => {
const downloadedBytes = validSafetensors();
const model = {
...FAKE_MODEL,
modelVersions: [
...FAKE_MODEL.modelVersions,
{
...FAKE_MODEL.modelVersions[0],
id: 8,
files: [{
...FAKE_MODEL.modelVersions[0].files[0],
downloadUrl: 'https://civitai.com/api/download/models/8',
}],
},
],
};
let releaseMetadata;
const metadataGate = new Promise((resolve) => { releaseMetadata = resolve; });
let metadataCalls = 0;
let downloadCalls = 0;
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/2600698')) {
metadataCalls += 1;
await metadataGate;
return mockJsonResponse(model);
}
if (url.startsWith('https://civitai.com/api/download/models/')) {
downloadCalls += 1;
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(downloadedBytes)); c.close(); },
});
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const version7 = lorasService.installFromCivitai({
url: 'https://civitai.com/models/2600698?modelVersionId=7',
}, { fetchImpl });
const version8 = lorasService.installFromCivitai({
url: 'https://civitai.com/models/2600698?modelVersionId=8',
}, { fetchImpl });
await vi.waitFor(() => expect(metadataCalls).toBe(2));
releaseMetadata();
const results = await Promise.all([version7, version8]);
expect(results.map((result) => result.civitai.versionId)).toEqual([7, 8]);
expect(downloadCalls).toBe(2);
});
it('releases the in-flight slot after a failed install so retry can proceed', async () => {
let metadataCalls = 0;
const fetchImpl = async () => {
metadataCalls += 1;
if (metadataCalls === 1) throw new Error('metadata unavailable');
return mockJsonResponse({ ...FAKE_MODEL, type: 'Checkpoint' });
};
await expect(
lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }),
).rejects.toThrow(/metadata unavailable/);
await expect(
lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }),
).rejects.toThrow(/not a LoRA/);
expect(metadataCalls).toBe(2);
});
it('refuses to install non-LoRA model types', async () => {
const fetchImpl = async () => (mockJsonResponse({ ...FAKE_MODEL, type: 'Checkpoint' }));
await expect(
lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }),
).rejects.toThrow(/not a LoRA/);
});
// previewCivitaiInstall shares its filename/guard logic with the real
// install (resolveCivitaiInstallPlan) — a preview that didn't share it
// would show a normal confirm dialog (size, destination, enabled Confirm)
// for a download that could never actually start.
it('previewCivitaiInstall refuses a non-LoRA model type, same as the real install', async () => {
const fetchImpl = async () => (mockJsonResponse({ ...FAKE_MODEL, type: 'Checkpoint' }));
await expect(
lorasService.previewCivitaiInstall({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }),
).rejects.toThrow(/not a LoRA/);
});
it('accepts LoRA-family types case-insensitively (DoRA, Lora, lycoris)', async () => {
// Civitai's `type` casing isn't stable in the wild — DoRA / LoHA / Lora
// / lower-case variants are all the same family from diffusers' POV.
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) {
return mockJsonResponse({ ...FAKE_MODEL, type: 'DoRA' });
}
const stream = new ReadableStream({ start(c) { c.enqueue(new Uint8Array(validSafetensors())); c.close(); } });
return { ok: true, status: 200, body: stream };
};
const sidecar = await lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl });
expect(sidecar.civitai.type).toBe('DoRA');
});
it('refuses to clobber an already-installed file', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-realstagram-v7.safetensors'), 'pre-existing');
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) return mockJsonResponse(FAKE_MODEL);
throw new Error(`should not download: ${url}`);
};
await expect(
lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }),
).rejects.toThrow(/Already installed/);
});
it('surfaces a friendly auth error when download is gated (no key)', async () => {
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) return mockJsonResponse(FAKE_MODEL);
return { ok: false, status: 401, statusText: 'Unauthorized' };
};
await expect(
lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }),
).rejects.toThrow(/Configure a Civitai API key in PortOS Settings/);
});
it('surfaces a different auth error message when a key was provided but download still fails', async () => {
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) return mockJsonResponse(FAKE_MODEL);
return { ok: false, status: 403, statusText: 'Forbidden' };
};
// Provide apiKey inline so hasApiKey=true
await expect(
lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698', apiKey: 'my-key' }, { fetchImpl }),
).rejects.toThrow(/even with your saved API key/);
});
it('atomic no-clobber: CIVITAI_ALREADY_INSTALLED when concurrent install wins the link race', async () => {
// Simulate a concurrent install winning by pre-creating the dest file
// AFTER the existsSync precheck passes but BEFORE link() runs. We do this
// by planting the dest file before the download — since our fetchImpl
// creates it synchronously (no real I/O delay) and the precheck is in
// installFromCivitai (before mkdir+download), we plant it inside the
// download body stream start to mimic the timing. The simplest way: make
// the download fetchImpl write the dest file first before returning.
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
const destFilename = 'lora-realstagram-v7.safetensors';
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) return mockJsonResponse(FAKE_MODEL);
if (url.startsWith('https://civitai.com/api/download/models/7')) {
// Plant the dest file to simulate a concurrent install winning before
// our link() call — this is what makes link() return EEXIST.
await fs.writeFile(join(tmpLoras, destFilename), 'other-install-won');
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(Buffer.from('race-loser'))); c.close(); },
});
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const err = await lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }).catch((e) => e);
expect(err.code).toBe('CIVITAI_ALREADY_INSTALLED');
// The original file written by the "winning" install must be preserved.
expect(existsSync(join(tmpLoras, destFilename))).toBe(true);
// The tmp .partial file must be cleaned up.
const tmpFiles = await fs.readdir(tmpLoras);
expect(tmpFiles.some((f) => f.endsWith('.partial'))).toBe(false);
});
it('rejects a truncated/corrupt download and deletes the partial file', async () => {
// A short download that isn't a parseable safetensors header — the leading
// non-Metal cause of "mosaic" garbage output at generate time (issue #2199).
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) return mockJsonResponse(FAKE_MODEL);
const stream = new ReadableStream({ start(c) { c.enqueue(new Uint8Array(Buffer.from('truncated'))); c.close(); } });
return { ok: true, status: 200, body: stream };
};
const err = await lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }).catch((e) => e);
expect(err.code).toBe('CIVITAI_LORA_CORRUPT');
// The corrupt file must be gone so the next install re-downloads.
expect(existsSync(join(tmpLoras, 'lora-realstagram-v7.safetensors'))).toBe(false);
// No sidecar should have been written.
expect(existsSync(join(tmpLoras, 'lora-realstagram-v7.safetensors.metadata.json'))).toBe(false);
});
it('rejects a structurally-valid download whose SHA-256 mismatches the Civitai digest', async () => {
const bytes = validSafetensors();
// A different, well-formed sha256 so the deep compare fails.
const wrongSha = 'f'.repeat(64);
const model = { ...FAKE_MODEL, modelVersions: [{ ...FAKE_MODEL.modelVersions[0], files: [{ ...FAKE_MODEL.modelVersions[0].files[0], hashes: { SHA256: wrongSha } }] }] };
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) return mockJsonResponse(model);
const stream = new ReadableStream({ start(c) { c.enqueue(new Uint8Array(bytes)); c.close(); } });
return { ok: true, status: 200, body: stream };
};
const err = await lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl }).catch((e) => e);
expect(err.code).toBe('CIVITAI_LORA_CORRUPT');
expect(existsSync(join(tmpLoras, 'lora-realstagram-v7.safetensors'))).toBe(false);
});
it('accepts a download whose SHA-256 matches the Civitai digest (case-insensitive)', async () => {
const bytes = validSafetensors();
// Civitai reports hashes in uppercase; sha256File returns lowercase.
const rightSha = sha256Hex(bytes).toUpperCase();
const model = { ...FAKE_MODEL, modelVersions: [{ ...FAKE_MODEL.modelVersions[0], files: [{ ...FAKE_MODEL.modelVersions[0].files[0], hashes: { SHA256: rightSha } }] }] };
const fetchImpl = async (url) => {
if (url.startsWith('https://civitai.com/api/v1/models/')) return mockJsonResponse(model);
const stream = new ReadableStream({ start(c) { c.enqueue(new Uint8Array(bytes)); c.close(); } });
return { ok: true, status: 200, body: stream };
};
const sidecar = await lorasService.installFromCivitai({ url: 'https://civitai.com/models/2600698' }, { fetchImpl });
expect(sidecar.filename).toBe('lora-realstagram-v7.safetensors');
expect(existsSync(join(tmpLoras, 'lora-realstagram-v7.safetensors'))).toBe(true);
});
});
describe('installFromHuggingface', () => {
const HF_MODEL = {
id: 'fal/ltx2.3-audio-reactive-lora',
tags: ['ltxv', 'lora'],
cardData: { base_model: 'Lightricks/LTX-2.3', instance_prompt: 'audio reactive' },
siblings: [
{ rfilename: 'README.md' },
{ rfilename: 'pytorch_lora_weights.safetensors' },
],
};
it('fetches metadata, downloads the .safetensors, writes a video-LoRA sidecar', async () => {
const calls = [];
const fetchImpl = async (url) => {
calls.push(url);
if (url.startsWith('https://huggingface.co/api/models/fal/ltx2.3-audio-reactive-lora')) {
return mockJsonResponse(HF_MODEL);
}
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors')) {
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(validSafetensors())); c.close(); },
});
return { ok: true, status: 200, headers: { get: (name) => (name === 'etag' ? '"lora-etag"' : null) }, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const sidecar = await lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl },
);
expect(sidecar.filename).toBe('lora-fal-ltx2.3-audio-reactive-lora-hf.safetensors');
expect(sidecar.runnerFamily).toBe('ltx-video');
expect(sidecar.source).toBe('huggingface');
expect(sidecar.huggingface.repo).toBe('fal/ltx2.3-audio-reactive-lora');
expect(sidecar.triggerWords).toEqual(['audio reactive']);
// The picked file is the canonical diffusers weights, not the README.
expect(calls.some((u) => u.includes('/resolve/main/pytorch_lora_weights.safetensors'))).toBe(true);
// downloadToFile's `finalize: false` means streamResumableDownload never
// runs its own etag-sidecar cleanup — a successful install must still
// remove it (nothing left it there for a future resume to use).
expect(existsSync(join(tmpLoras, `${sidecar.filename}.partial.etag`))).toBe(false);
});
// HF's model-metadata response never carries per-sibling sizes (the
// `blobs=true` expand is deliberately not requested), so the preflight
// must probe the resolved file's own Content-Length via a HEAD request —
// otherwise expectedBytes stays 0 and disk-insufficient can never fire.
it('previews the probed Content-Length when the metadata response has no sibling size', async () => {
const fetchImpl = async (url, opts = {}) => {
if (url.startsWith('https://huggingface.co/api/models/fal/ltx2.3-audio-reactive-lora')) {
return mockJsonResponse(HF_MODEL);
}
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors') && opts.method === 'HEAD') {
return { ok: true, status: 200, headers: { get: (name) => (name === 'content-length' ? '123456789' : null) } };
}
throw new Error(`unexpected fetch: ${url} ${opts.method || 'GET'}`);
};
const preview = await lorasService.previewHuggingfaceInstall(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl },
);
expect(preview.expectedBytes).toBe(123456789);
});
it('installs an exact versioned file beside the repo default', async () => {
const versionedModel = {
...HF_MODEL,
siblings: [
...HF_MODEL.siblings,
{ rfilename: 'ltx2.3_audio_reactive_lora_v2.safetensors' },
],
};
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) {
return mockJsonResponse(versionedModel);
}
if (url.includes('/resolve/main/ltx2.3_audio_reactive_lora_v2.safetensors')) {
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(validSafetensors())); c.close(); },
});
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const sidecar = await lorasService.installFromHuggingface(
{
url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora',
file: 'ltx2.3_audio_reactive_lora_v2.safetensors',
token: 'hf_test',
},
{ fetchImpl },
);
expect(sidecar.filename).toBe('lora-fal-ltx2.3-audio-reactive-lora-v2-hf.safetensors');
expect(sidecar.huggingface.file).toBe('ltx2.3_audio_reactive_lora_v2.safetensors');
expect(sidecar.name).toBe('ltx2.3-audio-reactive-lora · ltx2.3_audio_reactive_lora_v2');
expect(sidecar.recommendedScale).toBe(1.2);
});
it('refuses a repo it cannot classify as a supported family', async () => {
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) {
return mockJsonResponse({ id: 'someone/sdxl-lora', tags: ['sdxl'], siblings: [{ rfilename: 'lora.safetensors' }] });
}
throw new Error(`unexpected fetch: ${url}`);
};
await expect(
lorasService.installFromHuggingface({ url: 'someone/sdxl-lora', token: 'hf_test' }, { fetchImpl }),
).rejects.toMatchObject({ code: 'HF_UNKNOWN_FAMILY' });
});
it('reports byte-level download progress via onProgress', async () => {
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) {
return mockJsonResponse(HF_MODEL);
}
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors')) {
// Split a structurally-valid 10-byte safetensors blob across two chunks
// so the byte-progress accounting is exercised without tripping the
// post-download integrity check (issue #2199).
const bytes = validSafetensors();
const stream = new ReadableStream({
start(c) {
c.enqueue(new Uint8Array(bytes.subarray(0, 5)));
c.enqueue(new Uint8Array(bytes.subarray(5)));
c.close();
},
});
// Carry a Content-Length so the total is known.
return { ok: true, status: 200, body: stream, headers: { get: (h) => (h === 'content-length' ? String(bytes.length) : null) } };
}
throw new Error(`unexpected fetch: ${url}`);
};
const ticks = [];
await lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl, onProgress: (p) => ticks.push(p) },
);
expect(ticks.length).toBeGreaterThan(0);
// The flush tick always fires last with the full byte count.
const last = ticks[ticks.length - 1];
expect(last.received).toBe(10);
expect(last.total).toBe(10);
});
it('tolerates a missing Content-Length (total 0, still completes)', async () => {
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) {
return mockJsonResponse(HF_MODEL);
}
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors')) {
const stream = new ReadableStream({ start(c) { c.enqueue(new Uint8Array(validSafetensors())); c.close(); } });
return { ok: true, status: 200, body: stream }; // no headers
}
throw new Error(`unexpected fetch: ${url}`);
};
const ticks = [];
const sidecar = await lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl, onProgress: (p) => ticks.push(p) },
);
expect(sidecar.runnerFamily).toBe('ltx-video');
expect(ticks[ticks.length - 1]).toEqual({ received: 10, total: 0 });
});
it('lets an external AbortSignal cancel the in-flight weights download so an SSE disconnect stops it', async () => {
// The download claims a slot keyed on destPath and downloads through the
// SLOT's own AbortController (so a stall/cancel gets the same typed error
// regardless of who triggered it) — an external `signal` (the route's
// res.on('close') controller) is wired to cancel THROUGH the slot rather
// than being handed to fetch directly. Prove the wiring by aborting mid-
// transfer and asserting the actual weights fetch's signal aborts too.
const controller = new AbortController();
let sawSignal;
const fetchImpl = async (url, opts) => {
if (url.startsWith('https://huggingface.co/api/models/')) return mockJsonResponse(HF_MODEL);
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors')) {
// Plan resolution probes Content-Length with a separate timed HEAD
// before the download claims its slot. Observe only the slot-owned
// GET signal so the synchronous abort assertion cannot race that probe.
if (opts?.method === 'HEAD') {
return {
ok: true,
status: 200,
headers: new Map([['content-length', String(validSafetensors().length)]]),
};
}
sawSignal = opts?.signal;
// Never closes on its own: this stream only ends when the abort
// listener below errors it, mirroring how real fetch aborts an
// in-flight response body when its signal fires.
const stream = new ReadableStream({
start(c) {
c.enqueue(new Uint8Array(validSafetensors().slice(0, 8)));
sawSignal.addEventListener('abort', () => c.error(new Error('aborted')), { once: true });
},
});
return { ok: true, status: 200, body: stream, headers: new Map([['content-length', String(validSafetensors().length)]]) };
}
throw new Error(`unexpected fetch: ${url}`);
};
const install = lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl, signal: controller.signal },
);
await vi.waitFor(() => expect(sawSignal).toBeDefined());
expect(sawSignal.aborted).toBe(false);
controller.abort();
expect(sawSignal.aborted).toBe(true);
const err = await install.catch((e) => e);
expect(err.message).toMatch(/cancel/i);
expect(err.code).toBe('LORA_DOWNLOAD_CANCELLED');
});
it('refuses a second install of the same destination while the first is still downloading', async () => {
let release;
const gate = new Promise((resolve) => { release = resolve; });
const full = validSafetensors();
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) return mockJsonResponse(HF_MODEL);
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors')) {
const stream = new ReadableStream({
start(c) {
c.enqueue(new Uint8Array(full.slice(0, 8)));
gate.then(() => { c.enqueue(new Uint8Array(full.slice(8))); c.close(); });
},
});
return { ok: true, status: 200, body: stream, headers: new Map([['content-length', String(full.length)]]) };
}
throw new Error(`unexpected fetch: ${url}`);
};
const first = lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl },
);
const destPath = join(tmpLoras, 'lora-fal-ltx2.3-audio-reactive-lora-hf.safetensors');
await vi.waitFor(() => expect(existsSync(`${destPath}.partial`)).toBe(true));
const err = await lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl },
).catch((e) => e);
expect(err).toBeInstanceOf(Error);
expect(err.code).toBe('LORA_DOWNLOAD_IN_FLIGHT');
release();
await first;
});
it('installs a Flux.2 Klein 9B collection as flux2 and picks the klein9b file', async () => {
const characterSheet = {
id: 'Alissonerdx/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' },
],
};
const calls = [];
const fetchImpl = async (url) => {
calls.push(url);
if (url.startsWith('https://huggingface.co/api/models/Alissonerdx/CharacterSheet')) {
return mockJsonResponse(characterSheet);
}
if (url.includes('/resolve/main/QuadView_klein9b_v1.safetensors')) {
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(validSafetensors())); c.close(); },
});
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const sidecar = await lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/Alissonerdx/CharacterSheet' },
{ fetchImpl },
);
expect(sidecar.runnerFamily).toBe('flux2');
expect(sidecar.fluxVariant).toBe('9b');
expect(sidecar.huggingface.file).toBe('QuadView_klein9b_v1.safetensors');
expect(sidecar.filename).toBe('lora-alissonerdx-charactersheet-quadview-klein9b-v1-hf.safetensors');
expect(sidecar.name).toContain('QuadView_klein9b_v1');
expect(calls.some((u) => u.includes('QuadView_klein9b_v1.safetensors'))).toBe(true);
expect(calls.some((u) => u.includes('krea2'))).toBe(false);
});
it('installs a specific Klein 9B file when the pasted URL points at it', async () => {
const characterSheet = {
id: 'Alissonerdx/CharacterSheet',
tags: ['lora', 'flux.2-klein-9b'],
siblings: [
{ rfilename: 'QuadView_klein9b_v1.safetensors' },
{ rfilename: 'TripleView_klein9b_v1.safetensors' },
],
};
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/Alissonerdx/CharacterSheet')) {
return mockJsonResponse(characterSheet);
}
if (url.includes('/resolve/main/TripleView_klein9b_v1.safetensors')) {
const stream = new ReadableStream({
start(c) { c.enqueue(new Uint8Array(validSafetensors())); c.close(); },
});
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const sidecar = await lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/Alissonerdx/CharacterSheet/blob/main/TripleView_klein9b_v1.safetensors' },
{ fetchImpl },
);
expect(sidecar.huggingface.file).toBe('TripleView_klein9b_v1.safetensors');
expect(sidecar.runnerFamily).toBe('flux2');
expect(sidecar.fluxVariant).toBe('9b');
});
it('accepts an explicit family override', async () => {
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) {
return mockJsonResponse({ id: 'someone/mystery-lora', siblings: [{ rfilename: 'lora.safetensors' }] });
}
if (url.includes('/resolve/main/lora.safetensors')) {
const stream = new ReadableStream({ start(c) { c.enqueue(new Uint8Array(validSafetensors())); c.close(); } });
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const sidecar = await lorasService.installFromHuggingface(
{ url: 'someone/mystery-lora', family: 'ltx-video', token: 'hf_test' },
{ fetchImpl },
);
expect(sidecar.runnerFamily).toBe('ltx-video');
});
it('rejects a truncated/corrupt HF download and deletes the partial file', async () => {
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) return mockJsonResponse(HF_MODEL);
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors')) {
const stream = new ReadableStream({ start(c) { c.enqueue(new Uint8Array(Buffer.from('truncated'))); c.close(); } });
return { ok: true, status: 200, body: stream };
}
throw new Error(`unexpected fetch: ${url}`);
};
const err = await lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl },
).catch((e) => e);
expect(err.code).toBe('HF_LORA_CORRUPT');
expect(existsSync(join(tmpLoras, 'lora-fal-ltx2.3-audio-reactive-lora-hf.safetensors'))).toBe(false);
});
});
// #6190: loras.js is the third `streamResumableDownload` caller to register a
// slot — the orphaned-partial GC sweeps PATHS.loras but, before this, couldn't
// see a live LoRA download's `.partial` because loras.js claimed no slot.
describe('loras.js download-slot registration with the orphaned-partial GC', () => {
const HF_MODEL = {
id: 'fal/ltx2.3-audio-reactive-lora',
tags: ['ltxv', 'lora'],
cardData: { base_model: 'Lightricks/LTX-2.3', instance_prompt: 'audio reactive' },
siblings: [
{ rfilename: 'README.md' },
{ rfilename: 'pytorch_lora_weights.safetensors' },
],
};
const ANCIENT = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
it('protects a live LoRA download from the sweep even once its .partial is aged past the gate', async () => {
const { sweepOrphanedDownloadPartials } = await import('./orphanedPartialGc.js');
let release;
const gate = new Promise((resolve) => { release = resolve; });
const fetchImpl = async (url) => {
if (url.startsWith('https://huggingface.co/api/models/')) return mockJsonResponse(HF_MODEL);
if (url.includes('/resolve/main/pytorch_lora_weights.safetensors')) {
const full = validSafetensors();
const stream = new ReadableStream({
start(c) {
c.enqueue(new Uint8Array(full.slice(0, 8)));
gate.then(() => { c.enqueue(new Uint8Array(full.slice(8))); c.close(); });
},
});
return { ok: true, status: 200, body: stream, headers: new Map([['content-length', String(full.length)]]) };
}
throw new Error(`unexpected fetch: ${url}`);
};
const install = lorasService.installFromHuggingface(
{ url: 'https://huggingface.co/fal/ltx2.3-audio-reactive-lora', token: 'hf_test' },
{ fetchImpl },
);
const partialPath = join(tmpLoras, 'lora-fal-ltx2.3-audio-reactive-lora-hf.safetensors.partial');
await vi.waitFor(() => expect(existsSync(partialPath)).toBe(true));
const fs = await import('fs/promises');
await fs.utimes(partialPath, ANCIENT, ANCIENT);
expect(await sweepOrphanedDownloadPartials({ dirs: [tmpLoras] })).toMatchObject({ deleted: 0, keptProtected: 1 });
expect(existsSync(partialPath)).toBe(true);
release();
await install;
});
});
describe('LoRA key layout', () => {
const writeLora = async (name, header) => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, name), validSafetensors(header));
};
it('classifies and backfills keyLayout into the sidecar on list', async () => {
const fs = await import('fs/promises');
await writeLora('lora-comfy.safetensors', {
'diffusion_model.transformer_blocks.0.attn1.to_k.lora_A.weight': { dtype: 'F16', shape: [32, 2048], data_offsets: [0, 1] },
});
const list = await lorasService.listLoras();
expect(list.find((l) => l.filename === 'lora-comfy.safetensors').keyLayout).toBe('comfyui');
// Sidecar write is fire-and-forget; drain the queue it was enqueued on
// rather than polling for the file to appear.
await drainSidecarWrites();
const sidecar = JSON.parse(await fs.readFile(join(tmpLoras, 'lora-comfy.safetensors.metadata.json'), 'utf-8'));
expect(sidecar.keyLayout).toBe('comfyui');
});
it('prefers the stored sidecar layout over re-reading the header', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
// Unreadable file — a header read would yield null, so a 'comfyui' result
// can only have come from the sidecar.
await fs.writeFile(join(tmpLoras, 'lora-stored.safetensors'), 'garbage');
await fs.writeFile(join(tmpLoras, 'lora-stored.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-stored.safetensors', keyLayout: 'comfyui',
}));
const list = await lorasService.listLoras();
expect(list.find((l) => l.filename === 'lora-stored.safetensors').keyLayout).toBe('comfyui');
expect(await lorasService.getLoraKeyLayout('lora-stored.safetensors')).toBe('comfyui');
});
it('reports null (not not_a_lora) when the header is unreadable', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-corrupt.safetensors'), 'garbage');
const list = await lorasService.listLoras();
expect(list.find((l) => l.filename === 'lora-corrupt.safetensors').keyLayout).toBe(null);
expect(await lorasService.getLoraKeyLayout('lora-corrupt.safetensors')).toBe(null);
// Nothing persisted — a later read may succeed.
expect(existsSync(join(tmpLoras, 'lora-corrupt.safetensors.metadata.json'))).toBe(false);
});
it('getLoraKeyLayout classifies from the header when no sidecar exists', async () => {
await writeLora('lora-kohya.safetensors', {
'lora_unet_transformer_blocks_0_attn1_to_k.lora_down.weight': { dtype: 'F16', shape: [32, 2048], data_offsets: [0, 1] },
'lora_unet_transformer_blocks_0_attn1_to_k.lora_up.weight': { dtype: 'F16', shape: [2048, 32], data_offsets: [1, 2] },
});
expect(await lorasService.getLoraKeyLayout('lora-kohya.safetensors')).toBe('kohya');
});
});
describe('LoRA key layout — stored value validation', () => {
it('re-classifies when the sidecar holds an unrecognized layout string', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'lora-bogus.safetensors'), validSafetensors({
'diffusion_model.transformer_blocks.0.attn1.to_k.lora_A.weight': { dtype: 'F16', shape: [32, 2048], data_offsets: [0, 1] },
}));
await fs.writeFile(join(tmpLoras, 'lora-bogus.safetensors.metadata.json'), JSON.stringify({
filename: 'lora-bogus.safetensors', keyLayout: 'peft-ish',
}));
expect(await lorasService.getLoraKeyLayout('lora-bogus.safetensors')).toBe('comfyui');
const list = await lorasService.listLoras();
expect(list.find((l) => l.filename === 'lora-bogus.safetensors').keyLayout).toBe('comfyui');
});
});
describe('readTriggerWordsByFilename (#4665)', () => {
const writeSidecar = async (filename, body) => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, filename), 'fake-weights');
await fs.writeFile(join(tmpLoras, `${filename}.metadata.json`), JSON.stringify(body));
};
it('keys each LoRA basename to its sidecar trigger words', async () => {
await writeSidecar('aria.safetensors', { triggerWords: ['aria_tok', 'portrait'] });
await writeSidecar('grain.safetensors', { triggerWords: ['rstgrm'] });
expect(await lorasService.readTriggerWordsByFilename(['aria.safetensors', 'grain.safetensors'])).toEqual({
'aria.safetensors': ['aria_tok', 'portrait'],
'grain.safetensors': ['rstgrm'],
});
});
it('collapses an absolute path to its basename key (legacy sidecar replay)', async () => {
await writeSidecar('aria.safetensors', { triggerWords: ['aria_tok'] });
expect(await lorasService.readTriggerWordsByFilename([join(tmpLoras, 'aria.safetensors')]))
.toEqual({ 'aria.safetensors': ['aria_tok'] });
});
it('reads each LoRA once even when a basename and its path are both listed', async () => {
await writeSidecar('aria.safetensors', { triggerWords: ['aria_tok'] });
const out = await lorasService.readTriggerWordsByFilename([
'aria.safetensors',
join(tmpLoras, 'aria.safetensors'),
]);
expect(Object.keys(out)).toEqual(['aria.safetensors']);
});
it('omits a LoRA with no sidecar, and one whose sidecar predates triggerWords', async () => {
const fs = await import('fs/promises');
await fs.mkdir(tmpLoras, { recursive: true });
await fs.writeFile(join(tmpLoras, 'orphan.safetensors'), 'fake-weights');
await writeSidecar('legacy.safetensors', { name: 'Legacy' });
// Absent, not `[]` — the weave then skips it entirely rather than treating
// it as "read and found none".
expect(await lorasService.readTriggerWordsByFilename(['orphan.safetensors', 'legacy.safetensors'])).toEqual({});
});
it('keeps an explicitly-empty triggerWords array (Civitai reported none)', async () => {
await writeSidecar('none.safetensors', { triggerWords: [] });
expect(await lorasService.readTriggerWordsByFilename(['none.safetensors'])).toEqual({ 'none.safetensors': [] });
});
it('returns {} for an empty / non-array / junk-entry input without touching disk', async () => {
expect(await lorasService.readTriggerWordsByFilename([])).toEqual({});
expect(await lorasService.readTriggerWordsByFilename(null)).toEqual({});
expect(await lorasService.readTriggerWordsByFilename([null, '', 42])).toEqual({});
});
});