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, realpathSync, rmSync, statSync } from 'node:fs';
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
import {
AGENT_REGISTRY,
AGENTS_SKILLS_ROOT,
HUB_READER_EDITORS,
parsePathId,
RESERVED_PROJECT_SKILL_NAME,
USER_MCP_GATED_EDITOR_IDS,
} from '@inkeep/open-knowledge-core';
import { resolveBundledSkillDir } from '@inkeep/open-knowledge-server';
import { type ParseError, parse as parseJsonc } from 'jsonc-parser';
import {
EDITOR_TARGETS,
type EditorId,
type EditorMcpTarget,
entryCarriesOwnChain,
isOwnDevEntry,
} from '../commands/editors.ts';
import { replaceBundleDir } from './replace-bundle-dir.ts';
export class ProjectPathSafetyError extends Error {
override readonly name = 'ProjectPathSafetyError';
readonly code = 'PROJECT_PATH_SAFETY';
}
export function assertProjectPathSafe(targetPath: string, cwd: string): void {
let leafStat: ReturnType<typeof lstatSync> | undefined;
try {
leafStat = lstatSync(targetPath);
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
}
if (leafStat?.isSymbolicLink()) {
throw new ProjectPathSafetyError(
`Refusing to write through a symbolic link at ${targetPath}. ` +
'Remove the symlink and re-run project setup.',
);
}
assertProjectAncestorsContained(targetPath, cwd);
}
export function assertProjectRemovalSafe(targetPath: string, cwd: string): void {
assertProjectAncestorsContained(targetPath, cwd);
}
function assertProjectAncestorsContained(targetPath: string, cwd: string): void {
assertAncestorsContainedIn(targetPath, cwd);
}
export function assertAncestorsContainedIn(targetPath: string, base: string): void {
const cwd = base;
let realCwd: string;
try {
realCwd = realpathSync(cwd);
} catch {
realCwd = resolve(cwd);
}
let cursor = dirname(targetPath);
while (cursor.length > 1 && cursor !== sep) {
let cursorRealpath: string;
try {
cursorRealpath = realpathSync(cursor);
} catch (err) {
if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
cursor = dirname(cursor);
continue;
}
throw err;
}
const rel = relative(realCwd, cursorRealpath);
if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return;
throw new ProjectPathSafetyError(
`Refusing to write at ${targetPath}: ancestor ${cursor} resolves to ${cursorRealpath}, ` +
`which is outside the project directory ${realCwd}. A symbolic link in the path likely ` +
'escapes the project. Remove the symlink and re-run project setup.',
);
}
}
export interface ProjectSkillResult {
readonly editorId: EditorId;
readonly label: string;
readonly action:
| 'written'
| 'overwritten'
| 'skipped-unsupported'
| 'skipped-prerequisite'
| 'failed';
readonly path: string;
readonly error?: string;
}
export interface ProjectSkillWriteOptions {
readonly home?: string;
}
const MCP_CONFIG_MAX_BYTES = 10 * 1024 * 1024;
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
function configHasOpenKnowledgeEntry(
target: EditorMcpTarget,
cwd: string,
configPath: string,
): boolean {
try {
if (statSync(configPath).size > MCP_CONFIG_MAX_BYTES) return false;
} catch {
return false;
}
let raw: string;
try {
raw = readFileSync(configPath, 'utf-8');
} catch {
return false;
}
const errors: ParseError[] = [];
const parsed = parseJsonc(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw, errors, {
allowTrailingComma: true,
disallowComments: false,
});
if (errors.length > 0 || !isRecord(parsed)) return false;
const topLevel = parsed[target.topLevelKey];
if (!isRecord(topLevel)) return false;
const serverMap = target.serverMapSubKey ? topLevel[target.serverMapSubKey] : topLevel;
if (!isRecord(serverMap)) return false;
const entry = serverMap[target.serverName(cwd)];
if (isRecord(entry) && entry.enabled === false) return false;
return entryCarriesOwnChain(entry) || isOwnDevEntry(entry);
}
function sharedProjectMcpOwner(editor: EditorId): EditorMcpTarget | null {
const projectMcp = AGENT_REGISTRY[editor]?.satisfiers.find(
(satisfier) => satisfier.piece === 'mcp' && satisfier.scope === 'project',
);
const location = projectMcp?.pathId === undefined ? null : parsePathId(projectMcp.pathId);
if (location === null || location.kind !== 'editor-project-config') return null;
if (location.editor === editor) return null;
return EDITOR_TARGETS[location.editor] ?? null;
}
function isProjectSkillPrerequisiteMet(
target: EditorMcpTarget,
cwd: string,
options: ProjectSkillWriteOptions = {},
): boolean {
if (!USER_MCP_GATED_EDITOR_IDS.includes(target.id)) return true;
const owner = sharedProjectMcpOwner(target.id);
const sharedProjectConfig = owner?.projectConfigPath?.(cwd);
if (
owner !== null &&
sharedProjectConfig !== undefined &&
configHasOpenKnowledgeEntry(owner, cwd, sharedProjectConfig)
) {
return true;
}
try {
return configHasOpenKnowledgeEntry(target, cwd, target.configPath(cwd, options.home));
} catch {
return false;
}
}
export function hubReadersAmong(editorIds: readonly EditorId[]): EditorId[] {
const readers = new Set<string>(
HUB_READER_EDITORS.filter((r) => r.scope === 'project').map((r) => r.editorId),
);
return editorIds.filter((id) => readers.has(id));
}
export function writeProjectSkillToHub(
cwd: string,
editorIds: readonly EditorId[],
): ProjectSkillResult | null {
if (hubReadersAmong(editorIds).length === 0) return null;
const skillPath = join(cwd, AGENTS_SKILLS_ROOT, RESERVED_PROJECT_SKILL_NAME, 'SKILL.md');
try {
const sourceDir = resolveBundledSkillDir('project', { checkDesktop: true });
const targetDir = dirname(skillPath);
assertProjectPathSafe(targetDir, cwd);
return {
editorId: 'agents' as EditorId,
label: '.agents hub',
action: replaceBundleDir(sourceDir, skillPath),
path: skillPath,
};
} catch (err) {
return {
editorId: 'agents' as EditorId,
label: '.agents hub',
action: 'failed',
path: skillPath,
error: err instanceof Error ? err.message : String(err),
};
}
}
export function writeProjectSkill(
target: EditorMcpTarget,
cwd: string,
options: ProjectSkillWriteOptions = {},
): ProjectSkillResult {
const skillPath = target.projectSkillPath?.(cwd);
if (!skillPath) {
return {
editorId: target.id,
label: target.label,
action: 'skipped-unsupported',
path: '',
};
}
if (!isProjectSkillPrerequisiteMet(target, cwd, options)) {
return {
editorId: target.id,
label: target.label,
action: 'skipped-prerequisite',
path: skillPath,
};
}
try {
const sourceDir = resolveBundledSkillDir('project', { checkDesktop: true });
const targetDir = dirname(skillPath);
assertProjectPathSafe(targetDir, cwd);
const action = replaceBundleDir(sourceDir, skillPath);
return {
editorId: target.id,
label: target.label,
action,
path: skillPath,
};
} catch (err) {
return {
editorId: target.id,
label: target.label,
action: 'failed',
path: skillPath,
error: err instanceof Error ? err.message : String(err),
};
}
}
export interface ProjectSkillRemoveResult {
readonly editorId: EditorId;
readonly label: string;
readonly action: 'removed' | 'not-present' | 'skipped-unsupported' | 'failed';
readonly path: string;
readonly error?: string;
}
export function removeProjectSkill(target: EditorMcpTarget, cwd: string): ProjectSkillRemoveResult {
const skillPath = target.projectSkillPath?.(cwd);
if (!skillPath) {
return {
editorId: target.id,
label: target.label,
action: 'skipped-unsupported',
path: '',
};
}
try {
const targetDir = dirname(skillPath);
if (!existsSync(skillPath)) {
return {
editorId: target.id,
label: target.label,
action: 'not-present',
path: skillPath,
};
}
assertProjectRemovalSafe(targetDir, cwd);
rmSync(targetDir, { recursive: true, force: true });
return {
editorId: target.id,
label: target.label,
action: 'removed',
path: skillPath,
};
} catch (err) {
return {
editorId: target.id,
label: target.label,
action: 'failed',
path: skillPath,
error: err instanceof Error ? err.message : String(err),
};
}
}