Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, lstatSync, readFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import {
CONFIG_SCHEMA_MAJOR_PATH,
LOCAL_DIR,
OK_DIR,
OK_LEGACY_MACHINE_LOCAL_ROOT_DIRS,
OK_MACHINE_LOCAL_ROOT_FILES,
WORKTREES_DIRNAME,
} from '@inkeep/open-knowledge-core';
import { atomicTempPath } from '@inkeep/open-knowledge-core/server';
import {
tracedMkdirSync,
tracedRenameSync,
tracedRmSync,
tracedWriteFileSync,
} from './fs-traced.ts';
import { assertSafeProjectRoot } from './home-project-root.ts';
export const CONFIG_FILENAME = 'config.yml';
export class SymlinkRefusedError extends Error {
constructor(filePath: string, label: string) {
super(
`Refusing to follow symlink at ${label} (${filePath}). ` +
`An untrusted upstream may have committed this symlink to redirect writes outside the project. ` +
`Remove the symlink and re-run.`,
);
this.name = 'SymlinkRefusedError';
}
}
export function assertNotSymlink(filePath: string, label: string): void {
let lst: ReturnType<typeof lstatSync>;
try {
lst = lstatSync(filePath);
} catch (err) {
if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
throw err;
}
if (lst.isSymbolicLink()) {
throw new SymlinkRefusedError(filePath, label);
}
}
export function packageVersionMajorMinor(version: string): string {
const [rawMajor = '0', rawMinor = '0'] = version.split('.');
const major = rawMajor.length > 0 ? rawMajor : '0';
const minor = rawMinor.length > 0 ? rawMinor : '0';
return `${major}.${minor}`;
}
function quoteYamlScalar(value: string): string {
return /^[A-Za-z0-9._\-/]+$/.test(value) ? value : JSON.stringify(value);
}
export interface BuildConfigYmlOptions {
contentDir?: string;
}
export function buildConfigYmlContent(_version: string, options?: BuildConfigYmlOptions): string {
const template = `# yaml-language-server: $schema=https://unpkg.com/@inkeep/open-knowledge@latest/dist/schemas/${CONFIG_SCHEMA_MAJOR_PATH}/config.project.schema.json
# OpenKnowledge — project configuration
#
# This file overrides built-in defaults for this project. Every key below
# is commented out and shows its current default value. Uncomment any key
# to override it.
#
# Precedence (lowest -> highest):
# Built-in defaults
# -> ~/${OK_DIR}/global.yml (user defaults)
# -> ./${OK_DIR}/config.yml (this file)
#
# Schema reference: packages/core/src/config/schema.ts
# --- Content ---------------------------------------------------------------
# dir: where the CRDT editor reads/writes documents. Relative to the project
# root (the directory containing ${OK_DIR}/), NOT to this file.
#
# Path exclusions live in .okignore (gitignore syntax) at the project root,
# with nested .okignore files honored at any folder depth.
#
# content:
# dir: .
# --- Suggested lifecycle (optional pattern) --------------------------------
# Projects that want an explicit knowledge-maturation flow can organize as
# three tiers *relative to the content directory* — create the subfolders
# only when you need them:
#
# 1. external-sources/ — raw content fetched from URLs, PDFs. No analysis,
# just preservation. Use the \`ingest\` MCP tool.
# 2. research/ — analysis and synthesis. Provisional findings,
# trade-offs, open questions. Use the \`research\`
# MCP tool.
# 3. articles/ — canonical knowledge. Use the \`consolidate\` MCP
# tool to promote research -> articles once
# decisions are made.
#
# This is a pattern, not a requirement. Projects with existing layouts
# (\`specs/\`, \`reports/\`, \`docs/\`, etc.) should use those; the lifecycle
# exists as mental scaffolding, not as enforced filesystem structure.
# --- Server ----------------------------------------------------------------
# Bind host: \`--bind\` flag, \`HOST\` env var, or the \`server.bind\` config key
# (default: 127.0.0.1; \`0.0.0.0\` binds LAN-visible and also needs
# \`server.allowExternal\`). Port: \`--port\` flag, \`PORT\` env var, or
# \`server.port\` (auto-allocated if unset). See the Configuration reference.
# --- Appearance ------------------------------------------------------------
# Theme for the chrome. Defaults UNSET so the existing localStorage cache
# (\`ok-theme-v1\`) keeps powering FOUC-free first paint until you
# explicitly write here.
#
# appearance:
# theme: system # 'light' | 'dark' | 'system'
`;
const contentDir = options?.contentDir;
if (contentDir === undefined || contentDir === '.') return template;
return template.replace(
'# content:\n# dir: .',
`content:\n dir: ${quoteYamlScalar(contentDir)}`,
);
}
function writeIfMissing(filePath: string, content: string, label: string): boolean {
assertNotSymlink(filePath, label);
if (existsSync(filePath)) return false;
tracedWriteFileSync(filePath, content, 'utf-8');
return true;
}
export function ensureGitignoreEntries(
filePath: string,
scaffoldContent: string,
label = '.ok/.gitignore',
): 'created' | 'updated' | 'unchanged' {
assertNotSymlink(filePath, label);
if (!existsSync(filePath)) {
tracedWriteFileSync(filePath, scaffoldContent, 'utf-8');
return 'created';
}
const required = scaffoldContent
.split('\n')
.map((l) => l.trim())
.filter((l) => l.length > 0 && !l.startsWith('#'));
const existing = readFileSync(filePath, 'utf-8');
const present = new Set(existing.split('\n').map((l) => l.trim()));
const missing = required.filter((l) => !present.has(l));
if (missing.length === 0) return 'unchanged';
const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
tracedWriteFileSync(filePath, `${existing}${sep}${missing.join('\n')}\n`, 'utf-8');
return 'updated';
}
const RETIRED_PROJECT_SKILL_GITIGNORE_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/',
];
const RETIRED_PROJECT_SKILL_GITIGNORE_HEADER = [
'# 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.",
];
export function removeProjectSkillGitignoreBlock(projectDir: string): 'removed' | 'unchanged' {
const filePath = join(projectDir, '.gitignore');
assertNotSymlink(filePath, '.gitignore');
if (!existsSync(filePath)) return 'unchanged';
const original = readFileSync(filePath, 'utf-8');
const paths = new Set(RETIRED_PROJECT_SKILL_GITIGNORE_PATHS.map((p) => p.trim()));
const lines = original.split('\n');
if (!lines.some((l) => paths.has(l.trim()))) return 'unchanged';
const header = new Set(RETIRED_PROJECT_SKILL_GITIGNORE_HEADER);
const isBlank = (l: string): boolean => l.trim() === '';
const kept: string[] = [];
let atSeam = false;
for (const line of lines) {
if (paths.has(line.trim()) || header.has(line.trim())) {
atSeam = true;
continue;
}
if (atSeam && isBlank(line)) {
const previous = kept[kept.length - 1];
if (previous === undefined || isBlank(previous)) {
atSeam = false;
continue;
}
}
atSeam = false;
kept.push(line);
}
const next = kept.join('\n');
const tmpPath = atomicTempPath(filePath);
try {
tracedWriteFileSync(tmpPath, next, 'utf-8');
tracedRenameSync(tmpPath, filePath);
} catch (err) {
try {
tracedRmSync(tmpPath, { force: true });
} catch {}
throw err;
}
return 'removed';
}
const OK_GITIGNORE_CONTENT = `# .ok/local/ holds per-machine runtime state. Anything inside is
# machine-local and never committed. New runtime files (caches, locks,
# manifests, telemetry, error logs) are auto-ignored — no edit needed here.
${LOCAL_DIR}/
# .ok/worktrees/ holds git worktrees created from the desktop worktree
# selector — per-machine checkouts, never committed (WORKTREES_PARENT_DIR in
# @inkeep/open-knowledge-core). Worktree creation also appends this path to
# .git/info/exclude so projects whose committed rule predates it stay clean.
${WORKTREES_DIRNAME}/
# Machine-local directories left behind by projects that predate .ok/local/.
# Nothing writes them anymore, but a project that has them keeps them until
# someone deletes them, so they stay ignored.
${OK_LEGACY_MACHINE_LOCAL_ROOT_DIRS.map((name) => `${name}/`).join('\n')}
# Per-machine runtime state at the .ok/ root. Contains PII (principal email,
# UUID), hostnames, and absolute filesystem paths — never commit. The only
# file at .ok/ root that SHOULD be committed is \`config.yml\` (project
# configuration), which is explicitly NOT in this ignore list.
${OK_MACHINE_LOCAL_ROOT_FILES.join('\n')}
`;
export const OK_OKIGNORE_TEMPLATE = `# .okignore — paths to exclude from the OpenKnowledge document index.
# Uses gitignore syntax (parsed by the \`ignore\` npm library), evaluated
# alongside .gitignore in a single ignore-lib instance.
#
# Patterns combine with .gitignore: an entry here adds to exclusions, and
# a leading \`!\` re-includes a file that .gitignore excluded.
# Nested .okignore files at any folder depth are honored (mirrors .gitignore).
#
# Examples:
# drafts/ # exclude a directory
# *.draft.md # exclude files matching a pattern
# !keep.md # re-include a file .gitignore excluded
`;
export const ROOT_GITIGNORE_TEMPLATE = `# Seeded by OpenKnowledge when this project was created. Edit freely.
.DS_Store
.localized
Thumbs.db
thumbs.db
desktop.ini
Desktop.ini
.directory
`;
export interface InitContentOptions {
contentDir?: string;
packageVersion?: string;
}
export interface InitContentResult {
created: string[];
updated: string[];
skipped: string[];
}
export function initContent(projectDir: string, options?: InitContentOptions): InitContentResult {
assertSafeProjectRoot(projectDir);
const okDir = resolve(projectDir, OK_DIR);
const created: string[] = [];
const updated: string[] = [];
const skipped: string[] = [];
assertNotSymlink(okDir, '.ok/');
tracedMkdirSync(okDir, { recursive: true });
const gitignoreAction = ensureGitignoreEntries(join(okDir, '.gitignore'), OK_GITIGNORE_CONTENT);
if (gitignoreAction === 'created') {
created.push('.gitignore');
} else if (gitignoreAction === 'updated') {
updated.push('.gitignore');
} else {
skipped.push('.gitignore');
}
if (
writeIfMissing(
join(okDir, CONFIG_FILENAME),
buildConfigYmlContent(options?.packageVersion ?? '0.0.0', {
contentDir: options?.contentDir,
}),
`.ok/${CONFIG_FILENAME}`,
)
) {
created.push(CONFIG_FILENAME);
} else {
skipped.push(CONFIG_FILENAME);
}
if (writeIfMissing(join(projectDir, '.okignore'), OK_OKIGNORE_TEMPLATE, '.okignore')) {
created.push('.okignore');
} else {
skipped.push('.okignore');
}
return { created, updated, skipped };
}
export function writeRootGitignoreForNewRepo(projectDir: string): 'created' | 'skipped' {
return writeIfMissing(join(projectDir, '.gitignore'), ROOT_GITIGNORE_TEMPLATE, '.gitignore')
? 'created'
: 'skipped';
}