Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { homedir } from 'node:os';
import { join } from 'node:path';
import { DEV_FALLBACK_CLI_REFUSAL, OkCliCommand } from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import { classifyCloneError } from './clone-error-classify.ts';
import {
type RawCloneEvent,
type RunCloneController,
runCloneSubprocess,
UNSAFE_SYMLINKS_CLONE_MESSAGE,
validateCloneInputs,
} from './clone-flow.ts';
const okCli = (
cliArgs: readonly string[],
cliEnv?: Readonly<Record<string, string | undefined>>,
): OkCliCommand => OkCliCommand.resolve({ host: { cliArgs, cliEnv }, env: {} });
const HOME_PATH = join(homedir(), 'open-knowledge-test-clone');
const fixtureCli = (script: string): readonly string[] => [process.execPath, '-e', script];
describe('runCloneSubprocess', () => {
test('forwards progress + complete events parsed from stdout', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
console.log(JSON.stringify({type:'progress', phase:'receiving', pct:25}));
console.log(JSON.stringify({type:'progress', phase:'resolving', pct:80}));
console.log(JSON.stringify({type:'complete', dir:'/tmp/cloned-repo'}));
`),
),
url: 'https://github.com/octocat/hello.git',
dir: '/tmp/cloned-repo',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(3);
expect(events[0]).toEqual({ type: 'progress', phase: 'receiving', pct: 25 });
expect(events[1]).toEqual({ type: 'progress', phase: 'resolving', pct: 80 });
expect(events[2]).toEqual({ type: 'complete', dir: '/tmp/cloned-repo' });
});
test('a dev build without its workspace CLI reports the refusal and clones nothing', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: OkCliCommand.resolve({ env: { OK_CHANNEL: 'dev' } }),
url: 'https://github.com/octocat/hello.git',
dir: '/tmp/cloned-repo',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toEqual([{ type: 'error', message: DEV_FALLBACK_CLI_REFUSAL }]);
});
test('emits structured error event on nonzero exit, including stderr detail', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
process.stderr.write('fatal: repository not found\\n');
process.exit(128);
`),
),
url: 'https://github.com/octocat/missing.git',
dir: '/tmp/missing',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(1);
expect(events[0].type).toBe('error');
if (events[0].type === 'error') {
expect(events[0].message).toContain('exited with code 128');
expect(events[0].message).toContain('fatal: repository not found');
}
});
test('redacts a credential out of the stderr detail before it reaches the event', async () => {
const events: RawCloneEvent[] = [];
const token = `ghp_${'a'.repeat(36)}`;
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
process.stderr.write("fatal: could not read Password for 'https://${token}@github.com': terminal prompts disabled\\n");
process.exit(128);
`),
),
url: 'https://github.com/octocat/private.git',
dir: '/tmp/private',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(1);
expect(events[0].type).toBe('error');
if (events[0].type === 'error') {
expect(events[0].message).not.toContain(token);
expect(events[0].message).not.toContain('ghp_');
expect(events[0].message).toContain('***@github.com');
expect(events[0].message).toContain('exited with code 128');
}
});
test('caps a very long stderr detail so the toast stays readable', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
process.stderr.write('x'.repeat(3000) + '\\n');
process.exit(128);
`),
),
url: 'https://github.com/octocat/huge.git',
dir: '/tmp/huge',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(1);
expect(events[0].type).toBe('error');
if (events[0].type === 'error') {
expect(events[0].message).toContain('exited with code 128');
expect(events[0].message.length).toBeLessThan(600);
}
});
test('whitespace-only stderr produces no dangling detail separator', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
process.stderr.write(' \\n');
process.exit(128);
`),
),
url: 'https://github.com/octocat/blank.git',
dir: '/tmp/blank',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events[0].type).toBe('error');
if (events[0].type === 'error') {
expect(events[0].message).toBe('Clone process exited with code 128');
expect(events[0].message).not.toContain('—');
}
});
test('emits "Clone timed out" error on timeout', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(fixtureCli(`setInterval(() => {}, 1000)`)),
url: 'https://github.com/octocat/slow.git',
dir: '/tmp/slow',
timeoutMs: 100,
onEvent: (e) => events.push(e),
});
await ctrl.done;
const errEvent = events.find((e) => e.type === 'error');
expect(errEvent).toBeDefined();
if (errEvent?.type === 'error') {
expect(errEvent.message).toMatch(/timed out/i);
}
});
test('CLI-emitted error event is forwarded as terminal — no second event synthesized', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
console.log(JSON.stringify({type:'error', message:'permission denied'}));
process.exit(0);
`),
),
url: 'https://github.com/octocat/locked.git',
dir: '/tmp/locked',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(1);
expect(events[0]).toEqual({ type: 'error', message: 'permission denied' });
});
test('an unsafe-symlink refusal reaches the consumer with fixed wording and a structured path list', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
console.log(JSON.stringify({
type: 'error',
code: 'unsafe-symlinks',
message: 'permission denied: docs/permission denied.md',
refusedSymlinkPaths: ['docs/permission denied.md', 42, ''],
}));
`),
),
url: 'https://github.com/octocat/linked.git',
dir: '/tmp/linked',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toEqual([
{
type: 'error',
code: 'unsafe-symlinks',
message: UNSAFE_SYMLINKS_CLONE_MESSAGE,
refusedSymlinkPaths: ['docs/permission denied.md'],
},
]);
expect(classifyCloneError(UNSAFE_SYMLINKS_CLONE_MESSAGE).title).not.toMatch(/access/i);
});
test('CLI-emitted error message is redacted and capped before it reaches the consumer', async () => {
const events: RawCloneEvent[] = [];
const token = `ghp_${'b'.repeat(36)}`;
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
const message = "[auth] Failed to parse auth.yml at line 2:\\n token: ${token} " + "y".repeat(3000);
console.log(JSON.stringify({type:'error', message}));
`),
),
url: 'https://github.com/octocat/locked.git',
dir: '/tmp/locked',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(1);
expect(events[0].type).toBe('error');
if (events[0].type === 'error') {
expect(events[0].message).not.toContain(token);
expect(events[0].message).toContain('[REDACTED-GH-PAT]');
expect(events[0].message.length).toBeLessThanOrEqual(500);
}
});
test('CLI-emitted error message that redacts to nothing falls back to "Unknown error"', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
console.log(JSON.stringify({type:'error', message:' \\n '}));
`),
),
url: 'https://github.com/octocat/blank-msg.git',
dir: '/tmp/blank-msg',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toEqual([{ type: 'error', message: 'Unknown error' }]);
});
test('a cancel landing after the timeout still reports the timeout', async () => {
const events: RawCloneEvent[] = [];
const ctrl: RunCloneController = runCloneSubprocess({
cli: okCli(
fixtureCli(`
process.on('SIGTERM', () => {
console.log(JSON.stringify({type:'progress', phase:'terminating', pct:99}));
setTimeout(() => process.exit(7), 200);
});
setInterval(() => {}, 1000);
`),
),
url: 'https://github.com/octocat/slow.git',
dir: '/tmp/slow',
timeoutMs: 800,
onEvent: (e) => {
events.push(e);
if (e.type === 'progress') ctrl.cancel();
},
});
await ctrl.done;
const errEvent = events.find((e) => e.type === 'error');
expect(errEvent).toBeDefined();
if (errEvent?.type === 'error') {
expect(errEvent.message).toMatch(/timed out/i);
}
});
test('progress events with missing fields are dropped', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
console.log(JSON.stringify({type:'progress', phase:'receiving'}));
console.log(JSON.stringify({type:'complete', dir:'/tmp/x'}));
`),
),
url: 'https://github.com/x/y.git',
dir: '/tmp/x',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events.map((e) => e.type)).toEqual(['complete']);
});
test('synthesizes a complete event when CLI exits 0 without emitting one', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
// Emit only an invalid (missing dir) line, then clean exit. The runner
// ignores the malformed line and synthesizes a complete from opts.dir
// so the IPC stream consumer's iterator can resolve.
console.log(JSON.stringify({type:'complete'}));
process.exit(0);
`),
),
url: 'https://github.com/x/y.git',
dir: HOME_PATH,
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(1);
expect(events[0]).toEqual({ type: 'complete', dir: HOME_PATH });
});
test('unknown JSON event types are dropped, terminal still detected', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
console.log(JSON.stringify({type:'unknown-event', stuff:'ignored'}));
console.log(JSON.stringify({type:'complete', dir:'/tmp/y'}));
`),
),
url: 'https://github.com/x/y.git',
dir: '/tmp/y',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events.map((e) => e.type)).toEqual(['complete']);
});
test('cancel SIGTERMs the subprocess without synthesizing an error event', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(fixtureCli(`setInterval(() => {}, 1000)`)),
url: 'https://github.com/x/y.git',
dir: '/tmp/y',
onEvent: (e) => events.push(e),
});
setTimeout(() => ctrl.cancel(), 50);
await ctrl.done;
expect(events).toEqual([]);
});
test('forwards cliEnv through to the spawned CLI', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
console.log(JSON.stringify({type:'complete', dir: process.env.OK_CLONE_ENV_MARKER || 'unset'}));
`),
{ OK_CLONE_ENV_MARKER: '/tmp/marker-from-cli-env' },
),
url: 'https://github.com/octocat/hello.git',
dir: '/tmp/cloned-repo',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toEqual([{ type: 'complete', dir: '/tmp/marker-from-cli-env' }]);
});
test('handles a chunked stream that splits a JSON line across writes', async () => {
const events: RawCloneEvent[] = [];
const ctrl = runCloneSubprocess({
cli: okCli(
fixtureCli(`
process.stdout.write('{"type":"prog');
setTimeout(() => process.stdout.write('ress","phase":"receiving","pct":50}\\n'), 30);
setTimeout(() => console.log(JSON.stringify({type:'complete', dir:'/tmp/c'})), 60);
`),
),
url: 'https://github.com/x/y.git',
dir: '/tmp/c',
onEvent: (e) => events.push(e),
});
await ctrl.done;
expect(events).toHaveLength(2);
expect(events[0]).toEqual({ type: 'progress', phase: 'receiving', pct: 50 });
expect(events[1]).toEqual({ type: 'complete', dir: '/tmp/c' });
});
});
describe('validateCloneInputs', () => {
test('accepts allowed git URL + safe local path within home', () => {
expect(validateCloneInputs('https://github.com/octocat/hello.git', HOME_PATH)).toEqual({
ok: true,
});
});
test('rejects path outside the user home directory', () => {
const result = validateCloneInputs('https://github.com/x/y.git', '/etc/passwd-owner');
expect(result.ok).toBe(false);
expect(result.reason).toBe('invalid-dir');
});
test('accepts tilde-expansion paths', () => {
expect(validateCloneInputs('https://github.com/x/y.git', '~/Documents/repo').ok).toBe(true);
});
test('rejects disallowed URL protocol', () => {
const result = validateCloneInputs('javascript:alert(1)', '/tmp/x');
expect(result.ok).toBe(false);
expect(result.reason).toBe('invalid-url');
});
test('rejects path that is not safe for the local filesystem', () => {
const result = validateCloneInputs('https://github.com/x/y.git', '');
expect(result.ok).toBe(false);
expect(result.reason).toBe('invalid-dir');
});
test('reports invalid-url first when both fail (URL is checked first)', () => {
const result = validateCloneInputs('not-a-url', '');
expect(result.ok).toBe(false);
expect(result.reason).toBe('invalid-url');
});
});