Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
import {
AGENTS_SKILLS_ROOT,
containsXmlTag,
currentDesktopProduct,
EDITOR_PROJECT_SKILL_ROOT,
EDITOR_USER_SKILL_ROOT,
type EditorId,
editorProjectConfigPath,
PROJECT_SKILL_EDITOR_IDS,
RENAMED_PACK_SKILLS,
USER_SKILL_EDITOR_IDS,
} from '@inkeep/open-knowledge-core';
import type { SkillHostId } from '@inkeep/open-knowledge-core/skills-catalog';
import { parse as parseYaml } from 'yaml';
import { isSkillBundlePathWithheld } from './content-filter.ts';
import {
tracedCpSync,
tracedMkdirSync,
tracedRenameSync,
tracedRmSync,
tracedSymlinkSync,
} from './fs-traced.ts';
import { isInternalBundleSkillName } from './skill-bundles.ts';
import { inspectSkillPathEntry } from './skill-path-entry.ts';
export function resolvedHosts(hosts: readonly string[], scope: 'project' | 'global'): EditorId[] {
const valid = skillProjectionEditorIds(scope) as readonly string[];
return hosts.filter((h): h is EditorId => valid.includes(h));
}
const RESERVED_SKILL_PREFIX = 'open-knowledge';
const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
const CONFLICT_MARKER_RES = [/^<{7} /m, /^={7}$/m, /^>{7} /m];
function parseFrontmatter(raw: string): Record<string, unknown> | null {
const m = raw.match(FRONTMATTER_RE);
if (!m) return null;
try {
const parsed = parseYaml(m[1] ?? '');
return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
? (parsed as Record<string, unknown>)
: null;
} catch {
return null;
}
}
export interface SkillValidity {
ok: boolean;
errors: string[];
warnings: string[];
hasScripts: boolean;
}
export function validateSkillForInstall(
skillDir: string,
name: string,
opts?: { allowReservedName?: boolean },
): SkillValidity {
const errors: string[] = [];
const warnings: string[] = [];
const skillMd = join(skillDir, 'SKILL.md');
const hasScripts =
existsSync(join(skillDir, 'scripts')) && statSync(join(skillDir, 'scripts')).isDirectory();
const usesReservedName =
name.startsWith(RESERVED_SKILL_PREFIX) && RENAMED_PACK_SKILLS[name] === undefined;
if (!opts?.allowReservedName && usesReservedName) {
errors.push(
`"${name}" uses the reserved \`${RESERVED_SKILL_PREFIX}*\` prefix (reserved for OK's shipped skills) — choose another name.`,
);
}
if (!existsSync(skillMd)) {
errors.push(`No SKILL.md found at ${skillDir}.`);
return { ok: errors.length === 0, errors, warnings, hasScripts };
}
let raw: string;
try {
raw = readFileSync(skillMd, 'utf-8');
} catch (e) {
errors.push(`Cannot read SKILL.md: ${(e as Error).message}.`);
return { ok: false, errors, warnings, hasScripts };
}
if (CONFLICT_MARKER_RES.some((re) => re.test(raw))) {
errors.push(
'SKILL.md contains git conflict markers (`<<<<<<<` / `=======` / `>>>>>>>`). Resolve the conflict before installing.',
);
}
const fm = parseFrontmatter(raw);
if (fm === null) {
errors.push('SKILL.md has no valid `---` frontmatter block (name + description required).');
} else {
const fmName = fm.name;
const fmDesc = fm.description;
if (typeof fmName !== 'string' || fmName.length === 0) {
errors.push('SKILL.md frontmatter.name is missing or empty.');
} else if (fmName !== name) {
errors.push(
`SKILL.md frontmatter.name ("${fmName}") must equal the skill directory ("${name}").`,
);
}
if (typeof fmDesc !== 'string' || fmDesc.length === 0) {
warnings.push('This skill has no `description`. Add one so agents know when to use it.');
}
if (
(typeof fmName === 'string' && containsXmlTag(fmName)) ||
(typeof fmDesc === 'string' && containsXmlTag(fmDesc))
) {
errors.push(
'SKILL.md name/description contains XML tags (`<...>`), which break the skill loader.',
);
}
}
return { ok: errors.length === 0, errors, warnings, hasScripts };
}
function detectProjectConfiguredTargets(cwd: string): EditorId[] {
const product = currentDesktopProduct();
return PROJECT_SKILL_EDITOR_IDS.filter((id) => {
const rel = editorProjectConfigPath(id, product);
return rel !== null && existsSync(resolve(cwd, rel));
});
}
export function resolveSkillTargets(cwd: string, explicit?: readonly string[]): EditorId[] {
if (explicit && explicit.length > 0) {
const valid = new Set<string>(PROJECT_SKILL_EDITOR_IDS);
return explicit.filter((id): id is EditorId => valid.has(id));
}
return detectProjectConfiguredTargets(cwd);
}
export type SkillProjectionRoots = Record<EditorId, string | null>;
export function skillProjectionRoots(scope: 'project' | 'global'): SkillProjectionRoots {
return scope === 'global' ? EDITOR_USER_SKILL_ROOT : EDITOR_PROJECT_SKILL_ROOT;
}
export function skillProjectionEditorIds(scope: 'project' | 'global'): readonly EditorId[] {
return scope === 'global' ? USER_SKILL_EDITOR_IDS : PROJECT_SKILL_EDITOR_IDS;
}
export function skillHostDir(
cwd: string,
editor: EditorId,
name: string,
roots: SkillProjectionRoots = EDITOR_PROJECT_SKILL_ROOT,
): string | null {
const root = roots[editor];
return root === null ? null : resolve(cwd, root, name);
}
function skillTargetDir(
cwd: string,
target: SkillHostId,
name: string,
roots: SkillProjectionRoots = EDITOR_PROJECT_SKILL_ROOT,
): string | null {
if (target === 'agents') return resolve(cwd, AGENTS_SKILLS_ROOT, name);
return skillHostDir(cwd, target, name, roots);
}
export function hostSkillsRootEscapes(cwd: string, hostRoot: string): boolean {
if (!existsSync(hostRoot)) return false;
try {
const rel = relative(realpathSync(cwd), realpathSync(hostRoot));
return rel.startsWith('..') || isAbsolute(rel);
} catch {
return true;
}
}
function isAliasOfCanonicalRoot(hostRoot: string, canonicalRoot: string): boolean {
if (!existsSync(hostRoot) || !existsSync(canonicalRoot)) return false;
try {
return realpathSync(hostRoot) === realpathSync(canonicalRoot);
} catch {
return false;
}
}
function isSymlinkNotPermitted(err: unknown): boolean {
const code = (err as NodeJS.ErrnoException | null)?.code;
return code === 'EPERM' || code === 'EACCES';
}
export function linkOrCopySkillDir(
linkTarget: string,
dest: string,
source: string,
): 'link' | 'copy' {
try {
tracedSymlinkSync(linkTarget, dest, 'dir');
return 'link';
} catch (err) {
if (!isSymlinkNotPermitted(err)) throw err;
tracedRmSync(dest, { recursive: true, force: true });
tracedCpSync(source, dest, { recursive: true, dereference: true });
return 'copy';
}
}
export function linksNotPermittedWarning(locations: readonly string[]): string {
return `This system does not allow creating symlinks, so ${locations.join(', ')} got a copy instead of a link. On Windows, creating symlinks needs administrator rights or Developer Mode.`;
}
function skillLinkTarget(cwd: string, hostRoot: string, skillDir: string): string {
const absSkill = resolve(skillDir);
const fromCwd = relative(resolve(cwd), absSkill);
const insideProject = fromCwd !== '' && !fromCwd.startsWith('..') && !isAbsolute(fromCwd);
return insideProject ? relative(hostRoot, absSkill) : absSkill;
}
export function projectSkill(
skillDir: string,
name: string,
cwd: string,
targets: readonly EditorId[],
mode: 'symlink' | 'copy' = 'symlink',
roots: SkillProjectionRoots = EDITOR_PROJECT_SKILL_ROOT,
): EditorId[] {
const written: EditorId[] = [];
for (const editor of targets) {
const dest = skillHostDir(cwd, editor, name, roots);
if (dest === null) continue;
const hostRoot = dirname(dest);
if (hostSkillsRootEscapes(cwd, hostRoot)) continue;
if (isAliasOfCanonicalRoot(hostRoot, dirname(skillDir))) {
written.push(editor);
continue;
}
let sameEntry = resolve(dest) === resolve(skillDir);
if (!sameEntry && existsSync(dest)) {
try {
sameEntry = realpathSync(dest) === realpathSync(skillDir);
} catch {
sameEntry = false;
}
}
if (sameEntry) {
written.push(editor);
continue;
}
tracedRmSync(dest, { recursive: true, force: true });
tracedMkdirSync(hostRoot, { recursive: true });
if (mode === 'copy') {
tracedCpSync(skillDir, dest, { recursive: true, dereference: true });
} else {
linkOrCopySkillDir(skillLinkTarget(cwd, hostRoot, skillDir), dest, skillDir);
}
written.push(editor);
}
return written;
}
function isStaleBundleProjection(dest: string, name: string): boolean {
if (!isInternalBundleSkillName(name)) return false;
try {
if (lstatSync(dest).isSymbolicLink()) return false;
return existsSync(join(dest, 'SKILL.md'));
} catch {
return false;
}
}
export function classifyInPlaceDest(
dest: string,
canonicalAbs: string,
canonicalHash: string,
): 'absent' | 'canonical-dir' | 'link-to-canonical' | 'link' | 'same-copy' | 'different' {
const entry = inspectSkillPathEntry(dest, canonicalAbs, canonicalHash);
switch (entry.kind) {
case 'absent':
return 'absent';
case 'other':
return 'different';
case 'symlink':
return entry.resolution === 'target' ? 'link-to-canonical' : 'link';
case 'dir':
if (entry.identity === 'is-target') return 'canonical-dir';
return entry.identity === 'same-content' ? 'same-copy' : 'different';
}
}
export function projectInPlaceSkill(opts: {
canonicalAbs: string;
canonicalHash: string;
canonicalRootRel: string;
name: string;
cwd: string;
targets: readonly SkillHostId[];
mode?: 'copy' | 'link';
convertLinks?: boolean;
convertCopies?: boolean;
roots?: SkillProjectionRoots;
}): { hosts: SkillHostId[]; conflicted: SkillHostId[]; linkFallbacks: SkillHostId[] } {
const { canonicalAbs, canonicalHash, canonicalRootRel, name, cwd, targets } = opts;
const roots = opts.roots ?? EDITOR_PROJECT_SKILL_ROOT;
const mode = opts.mode ?? 'copy';
const hosts: SkillHostId[] = [];
const conflicted: SkillHostId[] = [];
const linkFallbacks: SkillHostId[] = [];
const materialize = (dest: string, hostRoot: string, editor: SkillHostId): void => {
tracedRmSync(dest, { recursive: true, force: true });
tracedMkdirSync(hostRoot, { recursive: true });
if (mode === 'link') {
if (
linkOrCopySkillDir(skillLinkTarget(cwd, hostRoot, canonicalAbs), dest, canonicalAbs) ===
'copy'
) {
linkFallbacks.push(editor);
}
} else {
tracedCpSync(canonicalAbs, dest, { recursive: true, dereference: true });
}
};
for (const editor of targets) {
if (
editor === 'agents'
? canonicalRootRel === AGENTS_SKILLS_ROOT
: roots[editor] === canonicalRootRel
) {
const own = skillTargetDir(cwd, editor, name, roots);
if (own !== null && !hostSkillsRootEscapes(cwd, dirname(own))) {
const cls = classifyInPlaceDest(own, canonicalAbs, canonicalHash);
if (
(mode === 'link' && opts.convertCopies === true && cls === 'same-copy') ||
(mode === 'copy' && opts.convertLinks === true && cls === 'link-to-canonical')
) {
materialize(own, dirname(own), editor);
}
}
hosts.push(editor);
continue;
}
const dest = skillTargetDir(cwd, editor, name, roots);
if (dest === null) continue;
const hostRoot = dirname(dest);
if (hostSkillsRootEscapes(cwd, hostRoot)) continue;
try {
const rootReal = realpathSync(hostRoot);
if (rootReal !== join(realpathSync(cwd), relative(cwd, hostRoot))) continue;
} catch {}
switch (classifyInPlaceDest(dest, canonicalAbs, canonicalHash)) {
case 'canonical-dir':
hosts.push(editor);
break;
case 'link-to-canonical':
if (mode === 'copy' && opts.convertLinks === true) materialize(dest, hostRoot, editor);
hosts.push(editor);
break;
case 'same-copy':
if (mode === 'link' && opts.convertCopies === true) materialize(dest, hostRoot, editor);
hosts.push(editor);
break;
case 'different':
if (isStaleBundleProjection(dest, name)) {
materialize(dest, hostRoot, editor);
hosts.push(editor);
break;
}
conflicted.push(editor);
break;
case 'link':
case 'absent':
materialize(dest, hostRoot, editor);
hosts.push(editor);
break;
}
}
return { hosts, conflicted, linkFallbacks };
}
export function relocateInPlaceCanonical(opts: {
canonicalAbs: string;
canonicalHash: string;
name: string;
cwd: string;
newTarget: SkillHostId;
destDirAbs?: string;
leaveLinkBehind?: boolean;
roots?: SkillProjectionRoots;
}): { ok: true; newAbs: string } | { ok: false; reason: 'target-unusable' | 'target-missing' } {
const { canonicalHash, name, cwd, newTarget } = opts;
const roots = opts.roots ?? EDITOR_PROJECT_SKILL_ROOT;
let canonicalAbs: string;
try {
canonicalAbs = realpathSync(opts.canonicalAbs);
} catch {
return { ok: false, reason: 'target-unusable' };
}
try {
if (lstatSync(canonicalAbs).isSymbolicLink() || !lstatSync(canonicalAbs).isDirectory()) {
return { ok: false, reason: 'target-unusable' };
}
} catch {
return { ok: false, reason: 'target-unusable' };
}
const dest = opts.destDirAbs ?? skillTargetDir(cwd, newTarget, name, roots);
if (dest === null) return { ok: false, reason: 'target-missing' };
if (resolve(dest) === canonicalAbs) return { ok: true, newAbs: dest };
const hostRoot = dirname(dest);
if (hostSkillsRootEscapes(cwd, hostRoot)) return { ok: false, reason: 'target-unusable' };
switch (classifyInPlaceDest(dest, canonicalAbs, canonicalHash)) {
case 'canonical-dir':
return { ok: true, newAbs: dest };
case 'different':
return { ok: false, reason: 'target-unusable' };
case 'same-copy':
try {
if (lstatSync(dest).isSymbolicLink() || !existsSync(join(dest, 'SKILL.md'))) {
return { ok: false, reason: 'target-unusable' };
}
} catch {
return { ok: false, reason: 'target-unusable' };
}
tracedRmSync(canonicalAbs, { recursive: true, force: true });
break;
case 'link':
case 'link-to-canonical':
tracedRmSync(dest, { recursive: true, force: true });
tracedMkdirSync(hostRoot, { recursive: true });
tracedRenameSync(canonicalAbs, dest);
break;
case 'absent':
tracedMkdirSync(hostRoot, { recursive: true });
tracedRenameSync(canonicalAbs, dest);
break;
}
if (!existsSync(join(dest, 'SKILL.md')) || lstatSync(dest).isSymbolicLink()) {
return { ok: false, reason: 'target-unusable' };
}
if (opts.leaveLinkBehind === true && !existsSync(canonicalAbs)) {
tracedSymlinkSync(skillLinkTarget(cwd, dirname(canonicalAbs), dest), canonicalAbs, 'dir');
}
repointSiblingLinks({
name,
cwd,
roots,
target: dest,
skip: [dest, canonicalAbs],
alsoClaim: [canonicalAbs, dest],
});
return { ok: true, newAbs: dest };
}
function targetHostsFor(roots: SkillProjectionRoots): readonly SkillHostId[] {
const scope = roots === EDITOR_USER_SKILL_ROOT ? 'global' : 'project';
return ['agents', ...(skillProjectionEditorIds(scope) as readonly SkillHostId[])];
}
export function hostSlotPaths(cwd: string, name: string, roots: SkillProjectionRoots): string[] {
return targetHostsFor(roots)
.map((host) => skillTargetDir(cwd, host, name, roots))
.filter((p): p is string => p !== null);
}
export function repointSiblingLinks(opts: {
name: string;
cwd: string;
roots: SkillProjectionRoots;
target: string;
slots?: readonly string[];
skip?: readonly string[];
alsoClaim?: readonly string[];
}): void {
const { name, cwd, roots, target } = opts;
const skip = new Set((opts.skip ?? []).map((p) => resolve(p)));
const claim = new Set((opts.alsoClaim ?? []).map((p) => resolve(p)));
const slots = opts.slots ?? hostSlotPaths(cwd, name, roots);
for (const sib of slots) {
if (skip.has(resolve(sib))) continue;
try {
if (!lstatSync(sib).isSymbolicLink()) continue;
} catch {
continue;
}
let resolved: string | null = null;
try {
resolved = realpathSync(sib);
} catch {
resolved = null;
}
if (resolved !== null && !claim.has(resolved)) continue;
tracedRmSync(sib, { recursive: true, force: true });
tracedSymlinkSync(skillLinkTarget(cwd, dirname(sib), target), sib, 'dir');
}
}
export function removeInPlaceSkillCopies(opts: {
canonicalAbs: string;
canonicalHash: string;
name: string;
cwd: string;
targets: readonly SkillHostId[];
roots?: SkillProjectionRoots;
}): SkillHostId[] {
const { canonicalHash, name, cwd, targets } = opts;
const roots = opts.roots ?? EDITOR_PROJECT_SKILL_ROOT;
let canonicalAbs: string;
try {
canonicalAbs = realpathSync(opts.canonicalAbs);
} catch {
return [];
}
const removed: SkillHostId[] = [];
for (const editor of targets) {
const dest = skillTargetDir(cwd, editor, name, roots);
if (dest === null) continue;
if (hostSkillsRootEscapes(cwd, dirname(dest))) continue;
switch (classifyInPlaceDest(dest, canonicalAbs, canonicalHash)) {
case 'same-copy':
case 'link':
case 'link-to-canonical':
tracedRmSync(dest, { recursive: true, force: true });
removed.push(editor);
break;
case 'different':
if (isStaleBundleProjection(dest, name)) {
tracedRmSync(dest, { recursive: true, force: true });
removed.push(editor);
}
break;
default:
break;
}
}
if (removed.length > 0) {
repointSiblingLinks({ name, cwd, roots, target: canonicalAbs });
}
return removed;
}
export function reverseProjectSkill(
name: string,
cwd: string,
targets: readonly EditorId[],
roots: SkillProjectionRoots = EDITOR_PROJECT_SKILL_ROOT,
): EditorId[] {
const removed: EditorId[] = [];
for (const editor of targets) {
const dest = skillHostDir(cwd, editor, name, roots);
if (dest === null) continue;
let present = false;
try {
lstatSync(dest);
present = true;
} catch {
present = false;
}
if (!present) continue;
tracedRmSync(dest, { recursive: true, force: true });
removed.push(editor);
}
return removed;
}
const MAX_BUNDLED_FILE_BYTES = 256 * 1024;
export function listSkillBundledFilePaths(skillDir: string): string[] {
try {
if (!existsSync(skillDir)) return [];
return listSkillFiles(skillDir).filter((rel) => rel !== 'SKILL.md');
} catch {
return [];
}
}
function listSkillFiles(dir: string, prefix = ''): string[] {
const out: string[] = [];
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
if (isSkillBundlePathWithheld(rel)) continue;
if (entry.isDirectory()) out.push(...listSkillFiles(join(dir, entry.name), rel));
else if (entry.isFile()) out.push(rel);
}
return out.sort();
}
export function readSkillBundledFiles(
skillDir: string,
): Array<{ path: string; text: string | null }> {
if (!existsSync(skillDir)) return [];
const out: Array<{ path: string; text: string | null }> = [];
for (const rel of listSkillFiles(skillDir)) {
if (rel === 'SKILL.md') continue;
let text: string | null = null;
try {
const buf = readFileSync(join(skillDir, rel));
if (buf.length <= MAX_BUNDLED_FILE_BYTES && !buf.includes(0)) {
text = buf.toString('utf-8');
}
} catch (err) {
if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') throw err;
text = null;
}
out.push({ path: rel, text });
}
return out;
}