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 { beforeEach, describe, expect, it, vi } from 'vitest';
import EventEmitter from 'node:events';
import { join } from 'node:path';
vi.mock('fs', () => ({ existsSync: vi.fn() }));
vi.mock('fs/promises', () => ({
access: vi.fn(),
mkdtemp: vi.fn(),
readdir: vi.fn(),
rename: vi.fn(),
rm: vi.fn(),
}));
vi.mock('../lib/childProcess.js', () => ({ spawn: vi.fn() }));
vi.mock('../lib/fileUtils.js', () => ({
ensureDir: vi.fn(),
PATHS: { repos: '/repos' },
}));
import { existsSync } from 'fs';
import { access, mkdtemp, readdir, rename, rm } from 'fs/promises';
import { spawn } from '../lib/childProcess.js';
import { cloneRepo, isDerivedClonePath, reapStaleCloneStaging, pullRepo, getCloneDir } from './repoCloner.js';
const REPOS_DIR = '/repos';
const OWNER_DIR = join(REPOS_DIR, 'acme');
const LOCAL_PATH = join(OWNER_DIR, 'widgets');
const STAGING_ROOT = join(OWNER_DIR, '.widgets-cloning-attempt');
const STAGING_PATH = join(STAGING_ROOT, 'widgets');
const createChild = () => {
const child = new EventEmitter();
child.stderr = new EventEmitter();
child.kill = vi.fn();
return child;
};
describe('cloneRepo', () => {
beforeEach(() => {
vi.clearAllMocks();
existsSync.mockImplementation(path => !String(path).endsWith('.git'));
mkdtemp.mockResolvedValue(STAGING_ROOT);
readdir.mockResolvedValue([]);
rename.mockResolvedValue();
rm.mockResolvedValue();
});
it('publishes a clone only after git completes in attempt-specific staging', async () => {
const child = createChild();
spawn.mockReturnValue(child);
const resultPromise = cloneRepo('https://github.com/acme/widgets');
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
expect(spawn).toHaveBeenCalledWith('git', [
'clone', '--depth', '1', '--single-branch',
'https://github.com/acme/widgets.git',
STAGING_PATH
], expect.objectContaining({ shell: false }));
expect(rename).not.toHaveBeenCalled();
child.emit('close', 0);
await expect(resultPromise).resolves.toMatchObject({
localPath: LOCAL_PATH,
alreadyCloned: false
});
expect(rename).toHaveBeenCalledWith(
STAGING_PATH,
LOCAL_PATH
);
expect(rm).toHaveBeenCalledWith(
STAGING_ROOT,
{ recursive: true, force: true }
);
});
it('clones a requested branch as a literal argument and surfaces a missing branch failure', async () => {
const child = createChild();
spawn.mockReturnValue(child);
const pending = cloneRepo('https://github.com/acme/widgets', { branch: 'feature/worlds' });
const rejected = expect(pending).rejects.toThrow('Remote branch feature/worlds not found');
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
expect(spawn).toHaveBeenCalledWith('git', [
'clone', '--depth', '1', '--single-branch', '--branch', 'feature/worlds',
'https://github.com/acme/widgets.git', STAGING_PATH
], expect.objectContaining({ shell: false }));
child.stderr.emit('data', Buffer.from('Remote branch feature/worlds not found'));
child.emit('close', 128);
await rejected;
expect(rename).not.toHaveBeenCalled();
expect(rm).toHaveBeenCalledWith(STAGING_ROOT, { recursive: true, force: true });
});
it('removes a legacy partial destination only for a recovered attempt', async () => {
const child = createChild();
spawn.mockReturnValue(child);
const resultPromise = cloneRepo('https://github.com/acme/widgets', { replaceIncomplete: true });
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
expect(rm).toHaveBeenCalledWith(LOCAL_PATH, { recursive: true, force: true });
child.emit('close', 0);
await resultPromise;
});
it('never removes the destination for an ordinary clone', async () => {
// `replaceIncomplete` is the ONLY thing licensed to delete a checkout the
// user may already be using; a plain clone must stage and rename instead.
const child = createChild();
spawn.mockReturnValue(child);
const resultPromise = cloneRepo('https://github.com/acme/widgets');
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
child.emit('close', 0);
await resultPromise;
expect(rm).not.toHaveBeenCalledWith(LOCAL_PATH, expect.anything());
});
it('discards staging and surfaces the git error when the clone fails', async () => {
const child = createChild();
spawn.mockReturnValue(child);
const resultPromise = cloneRepo('https://github.com/acme/widgets');
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
child.stderr.emit('data', Buffer.from('fatal: repository not found'));
child.emit('close', 128);
await expect(resultPromise).rejects.toThrow('fatal: repository not found');
// Nothing published, and the abandoned partial checkout is gone rather than
// left for the boot-time reaper.
expect(rename).not.toHaveBeenCalled();
expect(rm).toHaveBeenCalledWith(
STAGING_ROOT,
{ recursive: true, force: true }
);
});
it('keeps a checkout a concurrent attempt already published', async () => {
const child = createChild();
spawn.mockReturnValue(child);
const resultPromise = cloneRepo('https://github.com/acme/widgets');
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
// The rival attempt won while git was running.
existsSync.mockReturnValue(true);
child.emit('close', 0);
await expect(resultPromise).resolves.toMatchObject({
localPath: LOCAL_PATH,
alreadyCloned: true
});
expect(rename).not.toHaveBeenCalled();
});
});
describe('reapStaleCloneStaging', () => {
const directory = name => ({ name, isDirectory: () => true });
// The sweep walks a TREE now (a namespaced host and a GitLab subgroup each add
// a level), so the fixtures are a path → entries map rather than a call
// sequence — a sequence would silently encode one particular walk order.
const mockTree = (tree, { clones = [] } = {}) => {
readdir.mockImplementation(async (dir) => {
const entries = tree[String(dir)];
if (!entries) throw Object.assign(new Error('nope'), { code: 'ENOENT' });
if (entries instanceof Error) throw entries;
return entries;
});
// A directory holding `.git` is a finished clone; the sweep must not walk in.
access.mockImplementation(async (path) => {
if (!clones.includes(String(path).replace(/[/\\]\.git$/, ''))) throw Object.assign(new Error('nope'), { code: 'ENOENT' });
});
};
beforeEach(() => {
vi.clearAllMocks();
readdir.mockReset();
access.mockReset();
rm.mockResolvedValue();
vi.spyOn(console, 'error').mockImplementation(() => {});
});
it('reaps only expired PortOS clone staging directories', async () => {
mockTree({
[REPOS_DIR]: [directory('acme')],
[OWNER_DIR]: [
directory('.portos-clone-1000000000000-old123'),
directory('.portos-clone-1999999999999-new123'),
directory('widgets'),
],
}, { clones: [LOCAL_PATH] });
await expect(reapStaleCloneStaging({
cloneDir: REPOS_DIR,
now: 2000000000000
})).resolves.toBe(1);
expect(rm).toHaveBeenCalledTimes(1);
expect(rm).toHaveBeenCalledWith(
join(OWNER_DIR, '.portos-clone-1000000000000-old123'),
{ recursive: true, force: true }
);
// The finished clone is a leaf, not another namespace level.
expect(readdir).not.toHaveBeenCalledWith(LOCAL_PATH, expect.anything());
});
// The DEEPEST layout the host table allows: hostname + the full subgroup cap.
// A hardcoded sweep bound stops one level short of this and leaks the staging
// tree of every interrupted clone in a deeply-nested group.
it('reaps staging nested under a namespaced host and the deepest allowed subgroup path', async () => {
const hostDir = join(REPOS_DIR, 'gitlab.com');
const groupDir = join(hostDir, 'example-group');
const subgroupDir = join(groupDir, 'example-sub', 'example-sub-sub');
mockTree({
[REPOS_DIR]: [directory('gitlab.com')],
[hostDir]: [directory('example-group')],
[groupDir]: [directory('example-sub')],
[join(groupDir, 'example-sub')]: [directory('example-sub-sub')],
[subgroupDir]: [directory('.portos-clone-1000000000000-old123')],
});
await expect(reapStaleCloneStaging({
cloneDir: REPOS_DIR,
now: 2000000000000
})).resolves.toBe(1);
expect(rm).toHaveBeenCalledWith(
join(subgroupDir, '.portos-clone-1000000000000-old123'),
{ recursive: true, force: true }
);
});
it('reports an empty repos directory rather than throwing', async () => {
mockTree({});
await expect(reapStaleCloneStaging({ cloneDir: REPOS_DIR })).resolves.toBe(0);
expect(rm).not.toHaveBeenCalled();
});
it('keeps sweeping after an unreadable owner directory', async () => {
mockTree({
[REPOS_DIR]: [directory('locked'), directory('acme')],
[join(REPOS_DIR, 'locked')]: Object.assign(new Error('permission denied'), { code: 'EACCES' }),
[OWNER_DIR]: [directory('.portos-clone-1000000000000-old123')],
});
await expect(reapStaleCloneStaging({
cloneDir: REPOS_DIR,
now: 2000000000000
})).resolves.toBe(1);
expect(rm).toHaveBeenCalledWith(
join(OWNER_DIR, '.portos-clone-1000000000000-old123'),
{ recursive: true, force: true }
);
});
});
describe('cloneRepo across hosts', () => {
beforeEach(() => {
vi.clearAllMocks();
readdir.mockReset();
existsSync.mockReset();
access.mockReset();
existsSync.mockImplementation(path => !String(path).endsWith('.git'));
mkdtemp.mockImplementation(async (prefix) => `${prefix}staging`);
readdir.mockResolvedValue([]);
rename.mockResolvedValue();
rm.mockResolvedValue();
});
it('clones a gitlab.com project from its own host, under a hostname-namespaced path', async () => {
const child = createChild();
spawn.mockReturnValue(child);
const resultPromise = cloneRepo('https://gitlab.com/example-group/example-sub/example-repo');
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
child.emit('close', 0);
const [, args] = spawn.mock.calls[0];
expect(args).toContain('https://gitlab.com/example-group/example-sub/example-repo.git');
await expect(resultPromise).resolves.toMatchObject({
localPath: join(REPOS_DIR, 'gitlab.com', 'example-group', 'example-sub', 'example-repo'),
owner: 'example-group/example-sub',
repo: 'example-repo',
});
});
it('rejects a URL on an unsupported host', async () => {
await expect(cloneRepo('https://bitbucket.org/acme/widgets'))
.rejects.toThrow('Invalid repository URL');
expect(spawn).not.toHaveBeenCalled();
});
});
describe('isDerivedClonePath', () => {
const root = getCloneDir();
it('accepts only the path cloneRepo derives for the URL, on flat and namespaced hosts', () => {
expect(isDerivedClonePath('https://github.com/acme/widgets', join(root, 'acme', 'widgets'))).toBe(true);
expect(isDerivedClonePath('https://gitlab.com/acme/widgets', join(root, 'gitlab.com', 'acme', 'widgets'))).toBe(true);
expect(isDerivedClonePath('https://github.com/acme/widgets', join(root, 'acme', 'other'))).toBe(false);
expect(isDerivedClonePath('https://github.com/acme/widgets', join(root, 'acme', 'widgets', '..', '..', '..'))).toBe(false);
expect(isDerivedClonePath('https://github.com/acme/widgets', '/etc')).toBe(false);
expect(isDerivedClonePath('https://example.com/not-a-repo', join(root, 'acme', 'widgets'))).toBe(false);
expect(isDerivedClonePath('https://github.com/acme/widgets', null)).toBe(false);
});
});
describe('pullRepo', () => {
const localPath = '/local/repo';
beforeEach(() => {
vi.clearAllMocks();
existsSync.mockReturnValue(true);
});
const createChildWithStdout = () => {
const child = new EventEmitter();
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.kill = vi.fn();
return child;
};
it('clears the timeout when git pull exits successfully', async () => {
const child = createChildWithStdout();
spawn.mockReturnValue(child);
const resultPromise = pullRepo(localPath);
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
// Verify spawn was called with the correct git command
expect(spawn).toHaveBeenCalledWith('git', ['pull', '--ff-only'], expect.objectContaining({
cwd: localPath,
shell: false
}));
child.emit('close', 0);
const _result = await expect(resultPromise).resolves.toMatchObject({
success: true
});
// Verify that child.kill() was NOT called by the timeout
expect(child.kill).not.toHaveBeenCalled();
});
it('clears the timeout when git pull encounters an error', async () => {
const child = createChildWithStdout();
spawn.mockReturnValue(child);
const resultPromise = pullRepo(localPath);
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
child.stderr.emit('data', Buffer.from('fatal: not a git repository'));
child.emit('close', 128);
await expect(resultPromise).rejects.toThrow('Git pull failed');
// Verify that child.kill() was NOT called by the timeout
expect(child.kill).not.toHaveBeenCalled();
});
it('clears the timeout when the child process emits an error', async () => {
const child = createChildWithStdout();
spawn.mockReturnValue(child);
const resultPromise = pullRepo(localPath);
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
const testError = new Error('spawn failed');
child.emit('error', testError);
await expect(resultPromise).rejects.toThrow('spawn failed');
// Verify that child.kill() was NOT called by the timeout
expect(child.kill).not.toHaveBeenCalled();
});
it('rejects if the path is not a git repository', async () => {
existsSync.mockReturnValue(false);
await expect(pullRepo(localPath)).rejects.toThrow('Not a git repository');
expect(spawn).not.toHaveBeenCalled();
});
it('does not settle the promise twice when timeout fires after close event', async () => {
const child = createChildWithStdout();
spawn.mockReturnValue(child);
const resultPromise = pullRepo(localPath);
await vi.waitFor(() => expect(spawn).toHaveBeenCalled());
// Get a reference to the timeout so we can verify it was called
const _timeoutHandle = vi.useFakeTimers();
// Simulate close event
child.emit('close', 0);
// Attempt to fire the timeout (it should be cleared and not call reject)
// The real promise should resolve with the close event, not be rejected by timeout
const result = await resultPromise;
expect(result.success).toBe(true);
expect(child.kill).not.toHaveBeenCalled();
vi.useRealTimers();
});
});