Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
existsSync,
lstatSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
symlinkSync,
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import {
OK_DIR,
OK_MACHINE_LOCAL_ROOT_DIRS,
OK_MACHINE_LOCAL_ROOT_FILES,
} from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import {
buildConfigYmlContent,
initContent,
packageVersionMajorMinor,
ROOT_GITIGNORE_TEMPLATE,
removeProjectSkillGitignoreBlock,
writeRootGitignoreForNewRepo,
} from './init-project.ts';
describe('initContent', () => {
let testDir: string;
beforeEach(() => {
testDir = resolve(
tmpdir(),
`content-init-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
);
mkdirSync(testDir, { recursive: true });
});
afterEach(() => {
rmSync(testDir, { recursive: true, force: true });
});
it('creates config-only .ok/ scaffold from scratch', () => {
const result = initContent(testDir);
const okDir = join(testDir, OK_DIR);
expect(existsSync(okDir)).toBe(true);
expect(existsSync(join(okDir, 'local'))).toBe(false);
expect(existsSync(join(okDir, 'cache'))).toBe(false);
expect(existsSync(join(okDir, '.gitignore'))).toBe(true);
expect(existsSync(join(okDir, 'config.yml'))).toBe(true);
expect(existsSync(join(okDir, 'AGENTS.md'))).toBe(false);
expect(existsSync(join(okDir, 'articles'))).toBe(false);
expect(existsSync(join(okDir, 'external-sources'))).toBe(false);
expect(existsSync(join(okDir, 'research'))).toBe(false);
expect(result.created.length).toBeGreaterThan(0);
expect(result.skipped.length).toBe(0);
});
it('is idempotent — does not clobber existing files', () => {
initContent(testDir);
const configPath = join(testDir, OK_DIR, 'config.yml');
writeFileSync(configPath, 'custom content');
const result = initContent(testDir);
expect(readFileSync(configPath, 'utf-8')).toBe('custom content');
expect(result.skipped.length).toBeGreaterThan(0);
});
it('generates files with expected content', () => {
initContent(testDir);
const okDir = join(testDir, OK_DIR);
const gitignore = readFileSync(join(okDir, '.gitignore'), 'utf-8');
expect(gitignore).toContain('local/');
expect(gitignore).toContain('worktrees/');
const configYml = readFileSync(join(okDir, 'config.yml'), 'utf-8');
expect(configYml).toContain('OpenKnowledge — project configuration');
expect(configYml).toContain('# content:');
expect(configYml).toContain('# appearance:');
const activeLines = configYml
.split('\n')
.map((l) => l.trim())
.filter((l) => l.length > 0 && !l.startsWith('#'));
expect(activeLines).toEqual([]);
});
it('config.yml first line is the schema-version-pinned $schema magic comment', () => {
initContent(testDir);
const configYml = readFileSync(join(testDir, OK_DIR, 'config.yml'), 'utf-8');
const firstLine = configYml.split('\n')[0];
expect(firstLine).toMatch(
/^# yaml-language-server: \$schema=https:\/\/unpkg\.com\/@inkeep\/open-knowledge@latest\/dist\/schemas\/v\d+\/config\.project\.schema\.json$/,
);
expect(configYml.split('\n')[1]).toBe('# OpenKnowledge — project configuration');
expect(configYml).toContain('# Schema reference: packages/core/src/config/schema.ts');
});
it('config.yml scaffold does not teach the removed folders: key or a folder-metadata block', () => {
initContent(testDir);
const configYml = readFileSync(join(testDir, OK_DIR, 'config.yml'), 'utf-8');
expect(configYml).not.toContain('# folders:');
expect(configYml).not.toContain("# - match: 'external-sources/**'");
expect(configYml).not.toContain('Picomatch glob cheatsheet');
expect(configYml).not.toContain('exact structure');
expect(configYml).not.toContain('Folders: metadata & templates');
});
it('config.yml scaffold describes the suggested three-tier lifecycle', () => {
initContent(testDir);
const configYml = readFileSync(join(testDir, OK_DIR, 'config.yml'), 'utf-8');
expect(configYml).toContain('Suggested lifecycle');
expect(configYml).toContain('external-sources');
expect(configYml).toContain('research');
expect(configYml).toContain('articles');
});
it('appends missing scaffold entries to a stale legacy .gitignore (upgrade path)', () => {
const okDir = join(testDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
const stale = `cache/\nserver.lock\nui.lock\nsync-state.json\n`;
writeFileSync(join(okDir, '.gitignore'), stale, 'utf-8');
const result = initContent(testDir);
const after = readFileSync(join(okDir, '.gitignore'), 'utf-8');
expect(after).toBe(
`cache/\nserver.lock\nui.lock\nsync-state.json\nlocal/\nworktrees/\ntmp/\nprincipal.json\nstate.json\nconflicts.json\nlast-spawn-error.log\n`,
);
expect(result.updated).toContain('.gitignore');
expect(result.created).not.toContain('.gitignore');
});
it('preserves user-added .gitignore entries during scaffold merge', () => {
const okDir = join(testDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
const userCustomized = `cache/\nserver.lock\nmy-custom-ignore.tmp\n`;
writeFileSync(join(okDir, '.gitignore'), userCustomized, 'utf-8');
initContent(testDir);
const after = readFileSync(join(okDir, '.gitignore'), 'utf-8');
expect(after).toContain('my-custom-ignore.tmp');
expect(after).toContain('local/');
});
describe('symlink-guard against malicious upstream scaffold paths', () => {
it('refuses to follow .ok/.gitignore symlink with existing target (read-modify-write)', () => {
const okDir = join(testDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
const victim = resolve(testDir, 'victim-rc');
const victimContent = '#!/bin/sh\nexec /usr/local/bin/realprog\n';
writeFileSync(victim, victimContent, 'utf-8');
symlinkSync(victim, join(okDir, '.gitignore'));
expect(() => initContent(testDir)).toThrow(/symlink/i);
expect(readFileSync(victim, 'utf-8')).toBe(victimContent);
expect(lstatSync(join(okDir, '.gitignore')).isSymbolicLink()).toBe(true);
});
it('refuses to follow .ok/.gitignore symlink with non-existent target (write-creates-file)', () => {
const okDir = join(testDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
const phantomTarget = resolve(testDir, 'phantom-victim');
symlinkSync(phantomTarget, join(okDir, '.gitignore'));
expect(() => initContent(testDir)).toThrow(/symlink/i);
expect(existsSync(phantomTarget)).toBe(false);
});
it('refuses to follow .ok/config.yml symlink (writeIfMissing path)', () => {
const okDir = join(testDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
const phantomTarget = resolve(testDir, 'phantom-config');
symlinkSync(phantomTarget, join(okDir, 'config.yml'));
expect(() => initContent(testDir)).toThrow(/symlink/i);
expect(existsSync(phantomTarget)).toBe(false);
});
it('refuses to follow project-root .okignore symlink (writeIfMissing path)', () => {
const phantomTarget = resolve(testDir, 'phantom-okignore-target');
symlinkSync(phantomTarget, join(testDir, '.okignore'));
expect(() => initContent(testDir)).toThrow(/symlink/i);
expect(existsSync(phantomTarget)).toBe(false);
});
it('refuses to operate when .ok/ itself is a symlink (would redirect every scaffold write)', () => {
const decoy = resolve(testDir, 'decoy-dir');
mkdirSync(decoy, { recursive: true });
symlinkSync(decoy, join(testDir, OK_DIR));
expect(() => initContent(testDir)).toThrow(/symlink/i);
expect(existsSync(join(decoy, '.gitignore'))).toBe(false);
expect(existsSync(join(decoy, 'config.yml'))).toBe(false);
});
});
it('ignores every machine-local name the product can leave at the .ok/ root', () => {
initContent(testDir);
const lines = readFileSync(join(testDir, OK_DIR, '.gitignore'), 'utf-8')
.split('\n')
.map((l) => l.trim());
for (const name of OK_MACHINE_LOCAL_ROOT_FILES) {
expect(lines, `${name} must be ignored`).toContain(name);
}
for (const name of OK_MACHINE_LOCAL_ROOT_DIRS) {
expect(lines, `${name}/ must be ignored`).toContain(`${name}/`);
}
expect(lines).not.toContain('config.yml');
});
it('does not duplicate .gitignore entries on repeated initContent calls', () => {
initContent(testDir);
initContent(testDir);
initContent(testDir);
const gitignore = readFileSync(join(testDir, OK_DIR, '.gitignore'), 'utf-8');
const matches = gitignore.split('\n').filter((l) => l.trim() === 'local/').length;
expect(matches).toBe(1);
});
it('writes config.yml with content.dir override when contentDir option is set', () => {
const result = initContent(testDir, { contentDir: 'docs' });
expect(result.created).toContain('config.yml');
const configYml = readFileSync(join(testDir, OK_DIR, 'config.yml'), 'utf-8');
expect(configYml).toContain('content:\n dir: docs');
});
it('writes config.yml with default commented content.dir when contentDir is "."', () => {
initContent(testDir, { contentDir: '.' });
const configYml = readFileSync(join(testDir, OK_DIR, 'config.yml'), 'utf-8');
expect(configYml).toContain('# content:\n# dir: .');
});
});
describe('writeRootGitignoreForNewRepo', () => {
let testDir: string;
beforeEach(() => {
testDir = resolve(
tmpdir(),
`root-gitignore-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
);
mkdirSync(testDir, { recursive: true });
});
afterEach(() => {
rmSync(testDir, { recursive: true, force: true });
});
it('creates a project-root .gitignore from the template when absent', () => {
const action = writeRootGitignoreForNewRepo(testDir);
expect(action).toBe('created');
const written = readFileSync(join(testDir, '.gitignore'), 'utf-8');
expect(written).toBe(ROOT_GITIGNORE_TEMPLATE);
expect(written).toContain('.DS_Store\n');
expect(written).toContain('.localized\n');
expect(written).toContain('Thumbs.db\n');
expect(written).toContain('thumbs.db\n');
expect(written).toContain('desktop.ini\n');
expect(written).toContain('Desktop.ini\n');
expect(written).toContain('.directory\n');
});
it('skips when a project-root .gitignore already exists (writeIfMissing — user wins)', () => {
const original = 'node_modules/\n*.log\n';
writeFileSync(join(testDir, '.gitignore'), original, 'utf-8');
const action = writeRootGitignoreForNewRepo(testDir);
expect(action).toBe('skipped');
const after = readFileSync(join(testDir, '.gitignore'), 'utf-8');
expect(after).toBe(original);
});
it('refuses to follow a symlink at the .gitignore path (threat model: untrusted upstream)', () => {
const sentinel = join(testDir, 'sentinel.txt');
writeFileSync(sentinel, 'do-not-clobber', 'utf-8');
symlinkSync(sentinel, join(testDir, '.gitignore'));
expect(() => writeRootGitignoreForNewRepo(testDir)).toThrow(/Refusing to follow symlink/);
expect(readFileSync(sentinel, 'utf-8')).toBe('do-not-clobber');
expect(lstatSync(join(testDir, '.gitignore')).isSymbolicLink()).toBe(true);
});
});
describe('packageVersionMajorMinor', () => {
it('extracts MAJOR.MINOR from a 3-part semver', () => {
expect(packageVersionMajorMinor('1.2.3')).toBe('1.2');
expect(packageVersionMajorMinor('0.2.0')).toBe('0.2');
expect(packageVersionMajorMinor('10.20.30')).toBe('10.20');
});
it('drops prerelease suffixes from the minor segment (split-on-dot only consumes the first two)', () => {
expect(packageVersionMajorMinor('1.2.0-rc.1')).toBe('1.2');
});
it('falls back to 0.0 when the input is malformed', () => {
expect(packageVersionMajorMinor('')).toBe('0.0');
});
});
describe('buildConfigYmlContent', () => {
it('templates the magic comment with @latest + schema-major path', () => {
const out = buildConfigYmlContent('3.5.0');
expect(out.split('\n')[0]).toMatch(
/^# yaml-language-server: \$schema=https:\/\/unpkg\.com\/@inkeep\/open-knowledge@latest\/dist\/schemas\/v\d+\/config\.project\.schema\.json$/,
);
});
it('produces a file with NO uncommented top-level keys (idempotent at parse) — default options', () => {
const out = buildConfigYmlContent('1.0.0');
const activeLines = out
.split('\n')
.map((l) => l.trim())
.filter((l) => l.length > 0 && !l.startsWith('#'));
expect(activeLines).toEqual([]);
});
it('produces a file with NO uncommented top-level keys when contentDir is "."', () => {
const out = buildConfigYmlContent('1.0.0', { contentDir: '.' });
const activeLines = out
.split('\n')
.map((l) => l.trim())
.filter((l) => l.length > 0 && !l.startsWith('#'));
expect(activeLines).toEqual([]);
});
it('emits an active content.dir block when contentDir is a sub-path', () => {
const out = buildConfigYmlContent('1.0.0', { contentDir: 'docs' });
expect(out).toContain('content:\n dir: docs');
expect(out).not.toContain('# content:\n# dir: .');
const activeLines = out
.split('\n')
.map((l) => l.trim())
.filter((l) => l.length > 0 && !l.startsWith('#'));
expect(activeLines).toEqual(['content:', 'dir: docs']);
});
it('quotes contentDir with whitespace so emitted YAML parses', () => {
const out = buildConfigYmlContent('1.0.0', { contentDir: 'with spaces/sub' });
expect(out).toContain('content:\n dir: "with spaces/sub"');
});
it('precedence header points to user-global `~/.ok/global.yml`, not `config.yml`', () => {
const out = buildConfigYmlContent('1.0.0');
expect(out).toContain('~/.ok/global.yml');
expect(out).toContain('./.ok/config.yml');
expect(out).not.toContain('~/.ok/config.yml');
});
});
describe('removeProjectSkillGitignoreBlock', () => {
let testDir: string;
beforeEach(() => {
testDir = mkdtempSync(join(tmpdir(), 'ok-gitignore-drain-'));
});
afterEach(() => {
rmSync(testDir, { recursive: true, force: true });
});
const PATHS = [
'.claude/skills/open-knowledge/',
'.cursor/skills/open-knowledge/',
'.codex/skills/open-knowledge/',
'.github/skills/open-knowledge/',
'.opencode/skills/open-knowledge/',
'.pi/skills/open-knowledge/',
];
it('drains the bare-paths shape an existing .gitignore received', () => {
const path = join(testDir, '.gitignore');
writeFileSync(path, `# user-authored\nnode_modules/\n${PATHS.join('\n')}\n`, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('removed');
expect(readFileSync(path, 'utf-8')).toBe('# user-authored\nnode_modules/\n');
});
it('drains the header+paths shape OK wrote when it created the file', () => {
const path = join(testDir, '.gitignore');
writeFileSync(
path,
`${[
'# OpenKnowledge regenerates its built-in project skill on every open, and',
'# different app builds version-stamp it differently. It is a per-machine',
"# artifact — keep it out of git so teammates don't collide under auto-sync.",
...PATHS,
].join('\n')}\n`,
'utf-8',
);
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('removed');
expect(readFileSync(path, 'utf-8')).toBe('');
});
it('preserves every user line and collapses the blank the block left behind', () => {
const path = join(testDir, '.gitignore');
writeFileSync(path, `secrets.env\n\n${PATHS.join('\n')}\n\ndist/\n`, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('removed');
expect(readFileSync(path, 'utf-8')).toBe('secrets.env\n\ndist/\n');
});
it('idempotent, and inert for a project that never had the block', () => {
const path = join(testDir, '.gitignore');
const original = 'node_modules/\ndist/\n';
writeFileSync(path, original, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('unchanged');
expect(readFileSync(path, 'utf-8')).toBe(original);
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('unchanged');
});
it('no .gitignore at all is not an error', () => {
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('unchanged');
});
it('a user line that merely mentions the path survives', () => {
const path = join(testDir, '.gitignore');
const original = '# keep .claude/skills/open-knowledge/ around\n.claude/skills/*.bak\n';
writeFileSync(path, original, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('unchanged');
expect(readFileSync(path, 'utf-8')).toBe(original);
});
});
describe('removeProjectSkillGitignoreBlock touches only the seam it opened', () => {
let testDir: string;
beforeEach(() => {
testDir = mkdtempSync(join(tmpdir(), 'ok-gitignore-seam-'));
});
afterEach(() => {
rmSync(testDir, { recursive: true, force: true });
});
const PATHS = [
'.claude/skills/open-knowledge/',
'.cursor/skills/open-knowledge/',
'.codex/skills/open-knowledge/',
'.github/skills/open-knowledge/',
'.opencode/skills/open-knowledge/',
'.pi/skills/open-knowledge/',
];
it('leaves blank runs elsewhere in the file alone', () => {
const path = join(testDir, '.gitignore');
writeFileSync(path, `a/\n\n\nb/\n\n${PATHS.join('\n')}\n`, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('removed');
expect(readFileSync(path, 'utf-8')).toBe('a/\n\n\nb/\n');
});
it('keeps CRLF endings and whitespace-only lines as they were', () => {
const path = join(testDir, '.gitignore');
writeFileSync(path, `a/\r\n \r\nb/\r\n${PATHS.join('\r\n')}\r\n`, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('removed');
expect(readFileSync(path, 'utf-8')).toBe('a/\r\n \r\nb/\r\n');
});
it('leaves at most one blank where the block sat in the middle', () => {
const path = join(testDir, '.gitignore');
writeFileSync(path, `a/\n\n${PATHS.join('\n')}\n\nb/\n`, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('removed');
expect(readFileSync(path, 'utf-8')).toBe('a/\n\nb/\n');
});
it('writes the file through a rename, never leaving a truncated .gitignore', () => {
const path = join(testDir, '.gitignore');
writeFileSync(path, `a/\n${PATHS.join('\n')}\n`, 'utf-8');
expect(removeProjectSkillGitignoreBlock(testDir)).toBe('removed');
expect(readdirSync(testDir).filter((f) => f.startsWith('.gitignore.tmp'))).toEqual([]);
expect(readFileSync(path, 'utf-8')).toBe('a/\n');
});
});