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, beforeEach } from 'vitest';
const mocks = vi.hoisted(() => ({ execGit: vi.fn() }));
vi.mock('./execGit.js', () => ({ execGit: mocks.execGit }));
const ok = (stdout) => ({ stdout, stderr: '', exitCode: 0 });
const fail = (stderr = 'not a git repository') => ({ stdout: '', stderr, exitCode: 128 });
// Real `git status --porcelain=v2 --branch` output, captured from git itself —
// the parse is pinned against the actual format rather than an invented one.
const CLEAN = [
'# branch.oid 1234567890abcdef1234567890abcdef12345678',
'# branch.head main',
'# branch.upstream origin/main',
'# branch.ab +0 -0',
''
].join('\n');
const DIRTY = [
'# branch.oid 1234567890abcdef1234567890abcdef12345678',
'# branch.head main',
'1 .M N... 100644 100644 100644 0289925 0289925 server/index.js',
'? scratch.txt',
''
].join('\n');
async function loadModule() {
vi.resetModules();
return import('./buildIdentity.js');
}
describe('parsePorcelainV2', () => {
it('reads commit, short commit, and branch from the header', async () => {
const { parsePorcelainV2 } = await loadModule();
expect(parsePorcelainV2(CLEAN)).toEqual({
commit: '1234567890abcdef1234567890abcdef12345678',
shortCommit: '1234567',
branch: 'main',
dirty: false
});
});
it('treats any non-header line as a dirty tree', async () => {
const { parsePorcelainV2 } = await loadModule();
expect(parsePorcelainV2(DIRTY).dirty).toBe(true);
});
it('maps git\'s own absent spellings to null, not to a branch or commit', async () => {
const { parsePorcelainV2 } = await loadModule();
// `(initial)` is a repo with no commits; `(detached)` is not a branch name.
const initial = parsePorcelainV2('# branch.oid (initial)\n# branch.head main\n');
expect(initial.commit).toBeNull();
expect(initial.shortCommit).toBeNull();
const detached = parsePorcelainV2('# branch.oid abc1234\n# branch.head (detached)\n');
expect(detached.branch).toBeNull();
expect(detached.commit).toBe('abc1234');
});
it('reports null rather than an empty string for a blank header value', async () => {
const { parsePorcelainV2 } = await loadModule();
// An empty-string commit would compare unequal to every real commit and
// make the client's stale-bundle check report a permanent false mismatch.
const parsed = parsePorcelainV2('# branch.oid \n# branch.head \n');
expect(parsed.commit).toBeNull();
expect(parsed.branch).toBeNull();
});
it('does not mistake a header-only clean tree for dirty', async () => {
const { parsePorcelainV2 } = await loadModule();
expect(parsePorcelainV2('# branch.oid abc1234\n# branch.head main\n\n').dirty).toBe(false);
});
});
describe('getBuildIdentity', () => {
beforeEach(() => {
mocks.execGit.mockReset();
});
it('resolves the identity from a single git spawn', async () => {
mocks.execGit.mockResolvedValue(ok(CLEAN));
const { getBuildIdentity } = await loadModule();
const identity = await getBuildIdentity();
expect(identity.commit).toBe('1234567890abcdef1234567890abcdef12345678');
expect(identity.shortCommit).toBe('1234567');
expect(identity.branch).toBe('main');
expect(identity.dirty).toBe(false);
expect(mocks.execGit).toHaveBeenCalledTimes(1);
});
it('reports every field null outside a repo, and never throws', async () => {
mocks.execGit.mockResolvedValue(fail());
const { getBuildIdentity } = await loadModule();
const identity = await getBuildIdentity();
expect(identity.commit).toBeNull();
expect(identity.shortCommit).toBeNull();
expect(identity.branch).toBeNull();
// `null`, not `false` — "we could not tell" must stay distinguishable from
// "we checked and the tree is clean".
expect(identity.dirty).toBeNull();
});
it('survives a rejecting execGit (timeout / spawn failure) without throwing', async () => {
mocks.execGit.mockRejectedValue(new Error('git command timed out after 5s'));
const { getBuildIdentity } = await loadModule();
const identity = await getBuildIdentity();
expect(identity.commit).toBeNull();
expect(identity.dirty).toBeNull();
});
it('retries after a TRANSIENT probe failure instead of caching null forever', async () => {
// A 5s timeout can elapse once at boot while migrations hammer the disk.
// Caching that would disable the whole feature for the process lifetime on
// a checkout that is perfectly fine. The retry is behind a cooldown (see the
// storm test below), so the clock has to move for it to be attempted.
vi.useFakeTimers();
mocks.execGit.mockRejectedValueOnce(new Error('git command timed out after 5s'));
mocks.execGit.mockResolvedValue(ok(CLEAN));
const { getBuildIdentity } = await loadModule();
expect((await getBuildIdentity()).commit).toBeNull();
vi.advanceTimersByTime(60_000);
expect((await getBuildIdentity()).commit).toBe('1234567890abcdef1234567890abcdef12345678');
vi.useRealTimers();
});
it('does not re-spawn git per caller while a transient failure is cooling down', async () => {
// The identity is read per socket reconnect and per /api/system/build, and
// Socket.IO retries up to 10 times per tab — on a host where git is missing
// or wedged, an unbounded retry would spawn a git for every attempt.
mocks.execGit.mockRejectedValue(new Error('git command timed out after 5s'));
const { getBuildIdentity } = await loadModule();
await getBuildIdentity();
await getBuildIdentity();
await getBuildIdentity();
expect(mocks.execGit).toHaveBeenCalledTimes(1);
// Still reports not-known rather than throwing or inventing a value.
expect((await getBuildIdentity()).commit).toBeNull();
});
it('caches a DEFINITIVE not-a-repo answer rather than re-spawning git per request', async () => {
// git ran and told us there is no checkout (a tarball install). That cannot
// change under a running process, so one spawn is enough.
mocks.execGit.mockResolvedValue(fail());
const { getBuildIdentity } = await loadModule();
await getBuildIdentity();
await getBuildIdentity();
await getBuildIdentity();
expect(mocks.execGit).toHaveBeenCalledTimes(1);
});
it('shares one spawn across concurrent first callers', async () => {
// The boot log and an early health request can both land before the first
// probe resolves; caching the PROMISE (not the value) keeps that to one spawn.
mocks.execGit.mockResolvedValue(ok(CLEAN));
const { getBuildIdentity } = await loadModule();
const [a, b] = await Promise.all([getBuildIdentity(), getBuildIdentity()]);
expect(mocks.execGit).toHaveBeenCalledTimes(1);
expect(a).toBe(b);
});
it('does not re-probe git on later calls', async () => {
mocks.execGit.mockResolvedValue(ok(CLEAN));
const { getBuildIdentity } = await loadModule();
await getBuildIdentity();
await getBuildIdentity();
expect(mocks.execGit).toHaveBeenCalledTimes(1);
});
it('probes with ignoreExitCode and a bounded timeout, never the 30s default', async () => {
mocks.execGit.mockResolvedValue(ok(CLEAN));
const { getBuildIdentity } = await loadModule();
await getBuildIdentity();
const [args, cwd, options] = mocks.execGit.mock.calls[0];
expect(args).toEqual(['status', '--porcelain=v2', '--branch']);
expect(typeof cwd).toBe('string');
expect(cwd.trim()).not.toBe('');
expect(options.ignoreExitCode).toBe(true);
expect(options.timeout).toBeLessThanOrEqual(10_000);
});
it('never reports a path, hostname, username, or timestamp field', async () => {
mocks.execGit.mockResolvedValue(ok(CLEAN));
const { getBuildIdentity } = await loadModule();
// Privacy contract: the payload rides an API response and a socket frame,
// so its shape is pinned exactly rather than spot-checked for known-bad keys.
expect(Object.keys(await getBuildIdentity()).sort()).toEqual(
['branch', 'commit', 'dirty', 'shortCommit']
);
});
});
describe('formatBuildIdentity', () => {
it('renders commit, branch, and dirty state on one line', async () => {
const { formatBuildIdentity } = await loadModule();
expect(formatBuildIdentity({ shortCommit: 'abc1234', branch: 'main', dirty: false }))
.toBe('abc1234 (main)');
expect(formatBuildIdentity({ shortCommit: 'abc1234', branch: 'main', dirty: true }))
.toBe('abc1234 (main, dirty)');
expect(formatBuildIdentity({ shortCommit: 'abc1234', branch: null, dirty: false }))
.toBe('abc1234 (detached)');
expect(formatBuildIdentity({ shortCommit: 'abc1234', branch: 'main', dirty: null }))
.toBe('abc1234 (main, cleanliness unknown)');
});
it('says unknown rather than printing an empty parenthetical', async () => {
const { formatBuildIdentity } = await loadModule();
expect(formatBuildIdentity(null)).toBe('unknown (no git metadata)');
expect(formatBuildIdentity({ shortCommit: null, branch: null, dirty: null }))
.toBe('unknown (no git metadata)');
});
});
describe('getCachedBuildIdentity', () => {
beforeEach(() => {
mocks.execGit.mockReset();
});
it('is null until the probe resolves, then returns the identity', async () => {
// The boot banner reads this synchronously — it must never block, and must
// degrade to null rather than to a half-built tuple.
mocks.execGit.mockResolvedValue(ok(CLEAN));
const { getBuildIdentity, getCachedBuildIdentity } = await loadModule();
expect(getCachedBuildIdentity()).toBeNull();
const identity = await getBuildIdentity();
expect(getCachedBuildIdentity()).toBe(identity);
});
it('stays null after a TRANSIENT failure so the boot banner defers instead of lying', async () => {
// The banner reads this synchronously and prints whatever it gets. Parking
// an all-null tuple here would be truthy, so it would print "unknown" and
// never correct itself — the permanent lie this accessor must avoid.
mocks.execGit.mockRejectedValue(new Error('git command timed out after 5s'));
const { getBuildIdentity, getCachedBuildIdentity } = await loadModule();
await getBuildIdentity();
expect(getCachedBuildIdentity()).toBeNull();
});
it('caches the all-null identity too, so a non-repo does not re-probe forever', async () => {
mocks.execGit.mockResolvedValue(fail());
const { getBuildIdentity, getCachedBuildIdentity } = await loadModule();
await getBuildIdentity();
expect(getCachedBuildIdentity()).toEqual({
commit: null, shortCommit: null, branch: null, dirty: null
});
await getBuildIdentity();
expect(mocks.execGit).toHaveBeenCalledTimes(1);
});
});