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,
readdirSync,
readFileSync,
symlinkSync,
writeFileSync,
} from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { applySeed } from './apply.ts';
import { planSeed } from './plan.ts';
import { STARTER_PACKS } from './starter.ts';
const KNOWLEDGE_BASE_PACK = STARTER_PACKS['knowledge-base'];
const STARTER_FOLDERS = KNOWLEDGE_BASE_PACK.folders;
const STARTER_TEMPLATES = KNOWLEDGE_BASE_PACK.templates;
const LOG_MD_TEMPLATE = KNOWLEDGE_BASE_PACK.rootFiles?.['log.md'];
if (!LOG_MD_TEMPLATE) throw new Error('knowledge-base pack is missing log.md');
describe('applySeed — nested .ok/ era', () => {
let projectDir: string;
beforeEach(async () => {
projectDir = await mkdtemp(join(tmpdir(), 'seed-apply-'));
mkdirSync(join(projectDir, '.ok'), { recursive: true });
writeFileSync(join(projectDir, '.ok', 'config.yml'), '', 'utf-8');
});
afterEach(async () => {
await rm(projectDir, { recursive: true, force: true });
});
test('writes every starter folder + nested .ok/frontmatter.yml + starter template', async () => {
const plan = await planSeed({ projectDir });
const result = await applySeed(plan, { projectDir });
expect(result.errors).toEqual([]);
expect(result.applied).toBe(plan.created.length);
for (const folder of STARTER_FOLDERS) {
expect(existsSync(join(projectDir, folder.path))).toBe(true);
expect(existsSync(join(projectDir, folder.path, '.ok'))).toBe(true);
expect(existsSync(join(projectDir, folder.path, '.ok', 'frontmatter.yml'))).toBe(true);
expect(existsSync(join(projectDir, folder.path, '.ok', 'templates'))).toBe(true);
expect(
existsSync(
join(projectDir, folder.path, '.ok', 'templates', `${folder.starterTemplate}.md`),
),
).toBe(true);
}
expect(existsSync(join(projectDir, 'log.md'))).toBe(true);
});
test('refuses to write through a committed dangling symlinked leaf (no write-through)', async () => {
const plan = await planSeed({ projectDir });
const fileEntry = plan.created.find((e) => e.kind === 'file');
expect(fileEntry).toBeDefined();
const leafAbs = join(projectDir, (fileEntry as { path: string }).path);
const outsideTarget = join(tmpdir(), `seed-symlink-target-${process.pid}.yml`);
mkdirSync(join(leafAbs, '..'), { recursive: true });
symlinkSync(outsideTarget, leafAbs);
const result = await applySeed(plan, { projectDir });
expect(result.errors.some((e) => e.path === (fileEntry as { path: string }).path)).toBe(true);
expect(existsSync(outsideTarget)).toBe(false);
expect(lstatSync(leafAbs).isSymbolicLink()).toBe(true);
});
test('frontmatter.yml carries the folder defaults verbatim from STARTER_FOLDERS', async () => {
const plan = await planSeed({ projectDir });
await applySeed(plan, { projectDir });
for (const folder of STARTER_FOLDERS) {
const fmContent = readFileSync(
join(projectDir, folder.path, '.ok', 'frontmatter.yml'),
'utf-8',
);
expect(fmContent).toContain(folder.title);
expect(fmContent).toContain(folder.description.slice(0, 30));
for (const tag of folder.tags) {
expect(fmContent).toContain(`- ${tag}`);
}
}
});
test('starter template files contain the registered STARTER_TEMPLATES body verbatim', async () => {
const plan = await planSeed({ projectDir });
await applySeed(plan, { projectDir });
for (const folder of STARTER_FOLDERS) {
const tplContent = readFileSync(
join(projectDir, folder.path, '.ok', 'templates', `${folder.starterTemplate}.md`),
'utf-8',
);
expect(tplContent).toBe(STARTER_TEMPLATES[folder.starterTemplate]);
}
});
test('log.md gets the LOG_MD_TEMPLATE content verbatim', async () => {
const plan = await planSeed({ projectDir });
await applySeed(plan, { projectDir });
const logContent = readFileSync(join(projectDir, 'log.md'), 'utf-8');
expect(logContent).toBe(LOG_MD_TEMPLATE);
});
test('rerunning seed is idempotent — existing files are skipped, no errors', async () => {
const firstPlan = await planSeed({ projectDir });
const firstResult = await applySeed(firstPlan, { projectDir });
expect(firstResult.errors).toEqual([]);
const secondPlan = await planSeed({ projectDir });
const secondResult = await applySeed(secondPlan, { projectDir });
expect(secondResult.errors).toEqual([]);
expect(secondPlan.created).toEqual([]);
expect(secondResult.applied).toBe(0);
});
test('user-edited frontmatter.yml is preserved across reseed', async () => {
const plan1 = await planSeed({ projectDir });
await applySeed(plan1, { projectDir });
const fmPath = join(projectDir, 'external-sources', '.ok', 'frontmatter.yml');
const userEdit =
'title: My Custom External Sources\ndescription: edited by user\ntags:\n - mine\n';
writeFileSync(fmPath, userEdit, 'utf-8');
const plan2 = await planSeed({ projectDir });
await applySeed(plan2, { projectDir });
expect(readFileSync(fmPath, 'utf-8')).toBe(userEdit);
});
test('rootDir scopes apply under a subfolder', async () => {
const plan = await planSeed({ projectDir, rootDir: 'brain' });
const result = await applySeed(plan, { projectDir });
expect(result.errors).toEqual([]);
for (const folder of STARTER_FOLDERS) {
expect(existsSync(join(projectDir, 'brain', folder.path, '.ok', 'frontmatter.yml'))).toBe(
true,
);
expect(
existsSync(
join(
projectDir,
'brain',
folder.path,
'.ok',
'templates',
`${folder.starterTemplate}.md`,
),
),
).toBe(true);
}
expect(existsSync(join(projectDir, 'brain', 'log.md'))).toBe(true);
});
test('no adopted agent host: pack skills are skipped cleanly, not reported as errors', async () => {
const plan = await planSeed({ projectDir });
const result = await applySeed(plan, { projectDir });
expect(result.errors).toEqual([]);
expect(result.packSkillsInstalled).toEqual([]);
expect(existsSync(join(projectDir, '.claude'))).toBe(false);
expect(existsSync(join(projectDir, '.agents'))).toBe(false);
});
test('an adopted agent host receives the pack skills', async () => {
mkdirSync(join(projectDir, '.claude', 'skills'), { recursive: true });
const plan = await planSeed({ projectDir });
const result = await applySeed(plan, { projectDir });
expect(result.errors).toEqual([]);
expect(readdirSync(join(projectDir, '.claude', 'skills')).length).toBeGreaterThan(0);
});
test('reports an error for unknown template ids without crashing', async () => {
const result = await applySeed(
{
created: [
{
path: 'phantom/.ok/templates/unknown.md',
kind: 'file',
template: 'phantom/.ok/templates/unknown.md',
},
],
skipped: [],
warnings: [],
},
{ projectDir },
);
expect(result.applied).toBe(0);
expect(result.errors).toHaveLength(1);
expect(result.errors[0]?.error).toContain('No content template registered');
});
});
describe('applySeed — codebase-wiki nested folder paths + wiki/-prefixed rootFiles', () => {
let projectDir: string;
const WIKI_PACK = STARTER_PACKS['codebase-wiki'];
beforeEach(async () => {
projectDir = await mkdtemp(join(tmpdir(), 'seed-apply-wiki-'));
mkdirSync(join(projectDir, '.ok'), { recursive: true });
writeFileSync(join(projectDir, '.ok', 'config.yml'), '', 'utf-8');
});
afterEach(async () => {
await rm(projectDir, { recursive: true, force: true });
});
test('writes every nested wiki/<section> with .ok/frontmatter.yml + template and no errors', async () => {
const plan = await planSeed({ projectDir, packId: 'codebase-wiki' });
const result = await applySeed(plan, { projectDir, packId: 'codebase-wiki' });
expect(result.errors).toEqual([]);
expect(result.applied).toBe(plan.created.length);
for (const folder of WIKI_PACK.folders) {
expect(existsSync(join(projectDir, folder.path, '.ok', 'frontmatter.yml'))).toBe(true);
expect(
existsSync(
join(projectDir, folder.path, '.ok', 'templates', `${folder.starterTemplate}.md`),
),
).toBe(true);
}
});
test('nested frontmatter.yml resolves to the folder defaults (resolver tolerates the slash)', async () => {
const plan = await planSeed({ projectDir, packId: 'codebase-wiki' });
await applySeed(plan, { projectDir, packId: 'codebase-wiki' });
for (const folder of WIKI_PACK.folders) {
const fm = readFileSync(join(projectDir, folder.path, '.ok', 'frontmatter.yml'), 'utf-8');
expect(fm).toContain(folder.title);
for (const tag of folder.tags) expect(fm).toContain(`- ${tag}`);
}
});
test('template bodies resolve verbatim for nested folder paths', async () => {
const plan = await planSeed({ projectDir, packId: 'codebase-wiki' });
await applySeed(plan, { projectDir, packId: 'codebase-wiki' });
for (const folder of WIKI_PACK.folders) {
const tpl = readFileSync(
join(projectDir, folder.path, '.ok', 'templates', `${folder.starterTemplate}.md`),
'utf-8',
);
expect(tpl).toBe(WIKI_PACK.templates[folder.starterTemplate]);
}
});
test('wiki/-prefixed rootFiles land at wiki/OVERVIEW.md + wiki/log.md with verbatim content', async () => {
const plan = await planSeed({ projectDir, packId: 'codebase-wiki' });
const result = await applySeed(plan, { projectDir, packId: 'codebase-wiki' });
expect(result.errors).toEqual([]);
expect(readFileSync(join(projectDir, 'wiki', 'OVERVIEW.md'), 'utf-8')).toBe(
WIKI_PACK.rootFiles?.['wiki/OVERVIEW.md'],
);
expect(readFileSync(join(projectDir, 'wiki', 'log.md'), 'utf-8')).toBe(
WIKI_PACK.rootFiles?.['wiki/log.md'],
);
});
});
describe('applySeed — required plugins', () => {
let projectDir: string;
beforeEach(async () => {
projectDir = await mkdtemp(join(tmpdir(), 'seed-apply-plugins-'));
mkdirSync(join(projectDir, '.ok'), { recursive: true });
});
afterEach(async () => {
await rm(projectDir, { recursive: true, force: true });
});
async function seedOkfWith(body: string): Promise<{ after: string; enabled: string[] }> {
writeFileSync(join(projectDir, '.ok', 'config.yml'), body, 'utf-8');
const plan = await planSeed({ projectDir, packId: 'okf' });
const result = await applySeed(plan, { projectDir, packId: 'okf' });
expect(result.errors).toEqual([]);
return {
after: readFileSync(join(projectDir, '.ok', 'config.yml'), 'utf-8'),
enabled: result.pluginsEnabled,
};
}
test('turns the plugin back on even when the user had switched it off', async () => {
const { after, enabled } = await seedOkfWith('contentRules:\n okf:\n enabled: false\n');
expect(enabled).toEqual(['okf']);
expect(after).toMatch(/okf:\s*\n\s*enabled: true/);
});
test('leaves the rest of the user config standing', async () => {
const { after } = await seedOkfWith(
'# my notes\ncontentRules:\n okf:\n enabled: false\n markdownlint:\n enabled: true\n',
);
expect(after).toContain('# my notes');
expect(after).toMatch(/markdownlint:\s*\n\s*enabled: true/);
});
test('re-seeding an already-enabled project writes nothing', async () => {
const { after, enabled } = await seedOkfWith('contentRules:\n okf:\n enabled: true\n');
expect(enabled).toEqual([]);
expect(after).toBe('contentRules:\n okf:\n enabled: true\n');
});
test('a pack with no requirement reports none', async () => {
writeFileSync(join(projectDir, '.ok', 'config.yml'), '', 'utf-8');
const plan = await planSeed({ projectDir, packId: 'knowledge-base' });
const result = await applySeed(plan, { projectDir, packId: 'knowledge-base' });
expect(result.pluginsEnabled).toEqual([]);
expect(plan.requiredPlugins).toBeUndefined();
});
});