Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { type SpawnOptions, spawn } from 'node:child_process';
import { existsSync } from 'node:fs';
import { stat } from 'node:fs/promises';
import { homedir, platform as osPlatform } from 'node:os';
import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
import {
EDITOR_PROJECT_SKILL_ROOT,
type EditorId,
OPENKNOWLEDGE_SKILLS_REPO,
PROJECT_SKILL_EDITOR_IDS,
skillRootActivationPath,
USER_SKILL_HOSTS,
} from '@inkeep/open-knowledge-core';
import {
type BuildSkillZipResult,
buildSkillZip,
resolveBundledSkillDir,
} from './build-skill-zip.ts';
import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';
import { tracedCpSync, tracedMkdir, tracedMkdirSync, tracedRmSync } from './fs-traced.ts';
import { errnoCode } from './http/handler-utils.ts';
import { getLogger } from './logger.ts';
import { BUNDLE_SKILL_NAME, type BundleId } from './skill-bundles.ts';
import { recordSkillInstallEvent, type SkillInstallEventOutcome } from './skill-install-events.ts';
import { resolveSkillInstallReportSettings } from './skill-install-report-config.ts';
import { readKnownSkillPlacementRoots } from './skill-placements-store.ts';
import {
readBundleDecision,
readServerPackageVersion,
readTargetRecordedAt,
readTargetVersion,
type SkillStateLogger,
type SkillStateSurface,
writeTargetVersion,
} from './skill-state.ts';
import { reportSkillInstall } from './skills-sh-install-report.ts';
export type SkillInstallLogger = SkillStateLogger;
export type SpawnLike = (
command: string,
args: readonly string[],
opts: SpawnOptions,
) => ReturnType<typeof spawn>;
export interface InstallUserSkillOptions {
home?: string;
logger?: SkillInstallLogger;
surface?: SkillStateSurface;
bundleId?: BundleId;
force?: boolean;
}
export type InstallUserSkillResult = 'installed' | 'skip-current' | 'failed' | 'no-hosts';
const LEGACY_USER_SKILL_NAME = 'open-knowledge';
const CENTRAL_HOST_DIR = '.agents';
function centralSkillDir(home: string, bundleName: string): string {
return join(home, CENTRAL_HOST_DIR, 'skills', bundleName);
}
export interface DetectedSkillHost {
readonly hostDir: string;
readonly skillsRoot: string;
readonly editorId: EditorId;
}
export function detectUserSkillHosts(home: string): DetectedSkillHost[] {
return USER_SKILL_HOSTS.filter((host) => existsSync(join(home, host.hostDir)));
}
export interface ResolvedSkillHost {
readonly editor: string;
readonly skillsRoot: string;
readonly custom: boolean;
}
export function resolveBuiltinSkillHosts(home: string): ResolvedSkillHost[] {
const staticHosts: ResolvedSkillHost[] = detectUserSkillHosts(home).map((host) => ({
editor: host.editorId,
skillsRoot: host.skillsRoot,
custom: false,
}));
const seen = new Set(staticHosts.map((host) => host.skillsRoot));
const customHosts: ResolvedSkillHost[] = readKnownSkillPlacementRoots(home)
.filter((root) => !seen.has(root) && existsSync(join(home, root)))
.map((root) => ({ editor: root, skillsRoot: root, custom: true }));
return [...staticHosts, ...customHosts];
}
export function detectProjectSkillEditors(projectDir: string): EditorId[] {
return PROJECT_SKILL_EDITOR_IDS.filter((editorId) => {
const root = EDITOR_PROJECT_SKILL_ROOT[editorId];
return root !== null && existsSync(join(projectDir, skillRootActivationPath(root)));
});
}
async function installedUserSkillExists(home: string, bundleName: string): Promise<boolean> {
const candidates = detectUserSkillHosts(home).map((host) =>
join(home, host.skillsRoot, bundleName),
);
if (existsSync(join(home, CENTRAL_HOST_DIR))) {
candidates.push(centralSkillDir(home, bundleName));
}
for (const candidate of candidates) {
try {
if ((await stat(candidate)).isDirectory()) return true;
} catch {}
}
return false;
}
function removeLegacyUserSkillDirs(
home: string,
hosts: readonly DetectedSkillHost[],
logger: SkillInstallLogger,
): void {
const legacySkillRoots = [...hosts.map((host) => host.skillsRoot), `${CENTRAL_HOST_DIR}/skills`];
for (const skillsRoot of legacySkillRoots) {
const legacyDir = join(home, skillsRoot, LEGACY_USER_SKILL_NAME);
if (!existsSync(legacyDir)) continue;
try {
tracedRmSync(legacyDir, { recursive: true, force: true });
logger.info?.(
{ event: 'skill-install.legacy-removed', path: legacyDir },
'Removed pre-split `open-knowledge` user-global skill dir.',
);
} catch (err) {
logger.warn(
{ event: 'skill-install.legacy-remove-failed', path: legacyDir, err },
'Legacy `open-knowledge` skill removal failed; continuing with install.',
);
}
}
}
function replaceSkillDir(sourceDir: string, destDir: string): void {
tracedRmSync(destDir, { recursive: true, force: true });
tracedMkdirSync(dirname(destDir), { recursive: true });
tracedCpSync(sourceDir, destDir, { recursive: true });
}
interface SkillWriteEntry {
path: string;
status: 'written' | 'failed';
error?: string;
}
function writeBundleToHosts(
home: string,
bundleName: string,
sourceDir: string,
hosts: readonly DetectedSkillHost[],
includeCentral: boolean,
): SkillWriteEntry[] {
const entries: SkillWriteEntry[] = [];
const centralDest = centralSkillDir(home, bundleName);
const destinations = [
...(includeCentral ? [centralDest] : []),
...hosts
.map((host) => join(home, host.skillsRoot, bundleName))
.filter((dest) => dest !== centralDest),
];
for (const dest of destinations) {
try {
replaceSkillDir(sourceDir, dest);
entries.push({ path: dest, status: 'written' });
} catch (err) {
entries.push({
path: dest,
status: 'failed',
error: err instanceof Error ? err.message : String(err),
});
}
}
return entries;
}
export async function installUserSkill(
opts: InstallUserSkillOptions = {},
): Promise<InstallUserSkillResult> {
const home = opts.home ?? homedir();
const logger: SkillInstallLogger = opts.logger ?? {
warn: (data, message) => getLogger('skills').warn(data, message),
info: (data, message) => getLogger('skills').info(data, message),
};
const surfaceAttribution: SkillStateSurface = opts.surface ?? 'cli-npx-skills-add';
const bundleId = opts.bundleId ?? 'discovery';
const bundleName = BUNDLE_SKILL_NAME[bundleId];
if (!isAbsolute(home)) {
logger.warn(
{ event: 'skill-install.failed', reason: 'home-not-absolute', home },
'Skill install aborted — $HOME is not an absolute path.',
);
return 'failed';
}
const report = async (
outcome: SkillInstallEventOutcome,
version?: string,
reason?: string,
): Promise<void> => {
await recordSkillInstallEvent(
{
ts: new Date().toISOString(),
surface: surfaceAttribution,
target: 'cli-hosts',
bundle: bundleId,
outcome,
...(version !== undefined ? { version } : {}),
...(reason !== undefined ? { reason } : {}),
},
{ homedir: () => home, warn: logger.warn },
);
};
let declined: boolean | null;
try {
declined = await readBundleDecision(home, bundleName, logger);
} catch (err) {
logger.warn(
{ event: 'skill-install.gate.decision-read-failed', bundle: bundleId, err },
'Could not read the opt-out decision; skipping the install rather than risk reversing it.',
);
await report('skip-current', undefined, 'decision-read-failed');
return 'skip-current';
}
if (declined === false) {
logger.info?.(
{ event: 'skill-install.declined', bundle: bundleId },
'Bundle is opted out; skipping user-global skill install.',
);
await report('skip-current', undefined, 'declined');
return 'skip-current';
}
let currentVersion: string;
try {
currentVersion = await readServerPackageVersion();
} catch (err) {
logger.warn(
{ event: 'skill-install.failed', reason: 'version-read-failed', err },
'Skill install aborted — could not read @inkeep/open-knowledge-server version.',
);
await report('failed', undefined, 'version-read-failed');
return 'failed';
}
const existingVersion = await readTargetVersion(home, 'cli-hosts', logger).catch((err) => {
logger.warn(
{ event: 'skill-install.gate.read-failed', err },
'Could not read cli-hosts install-state; proceeding with fresh install.',
);
return null;
});
if (!opts.force && existingVersion !== null && existingVersion === currentVersion) {
if (await installedUserSkillExists(home, bundleName)) {
logger.info?.(
{ event: 'skill-install.skip-current', version: currentVersion },
'OpenKnowledge skill already installed at current version; skipping.',
);
await report('skip-current', currentVersion);
return 'skip-current';
}
logger.info?.(
{
event: 'skill-install.reinstall-missing',
version: currentVersion,
},
'Sidecar matches current version but skill files are missing; reinstalling.',
);
}
let bundleDir: string;
try {
bundleDir = resolveBundledSkillDir(bundleId, { checkDesktop: false });
} catch (err) {
logger.warn(
{
event: 'skill-install.failed',
reason: 'bundled-asset-missing',
err,
},
'Skill install aborted — bundled SKILL.md asset not found.',
);
await report('failed', currentVersion, 'bundled-asset-missing');
return 'failed';
}
const hosts = detectUserSkillHosts(home);
const includeCentral = existsSync(join(home, CENTRAL_HOST_DIR));
if (hosts.length === 0 && !includeCentral) {
logger.info?.(
{ event: 'skill-install.no-hosts', version: currentVersion },
'No supported agent host detected; skipping user-global skill install.',
);
await report('skip-current', currentVersion, 'no-hosts');
return 'no-hosts';
}
removeLegacyUserSkillDirs(home, hosts, logger);
const entries = writeBundleToHosts(home, bundleName, bundleDir, hosts, includeCentral);
const written = entries.filter((e) => e.status === 'written');
const failed = entries.filter((e) => e.status === 'failed');
if (written.length === 0) {
logger.warn(
{ event: 'skill-install.failed', reason: 'write-failed', entries: failed },
'Skill install failed — every destination write errored.',
);
await report('failed', currentVersion, 'write-failed');
return 'failed';
}
try {
await writeTargetVersion(home, 'cli-hosts', currentVersion, surfaceAttribution, logger);
} catch (err) {
logger.warn(
{ event: 'skill-install.failed', reason: 'sidecar-write-failed', err },
'Skill install succeeded but sidecar write failed.',
);
await report('failed', currentVersion, 'sidecar-write-failed');
return 'failed';
}
if (failed.length > 0) {
logger.warn(
{ event: 'skill-install.partial', version: currentVersion, entries: failed },
'Some agent hosts could not be written; the remaining copies are installed.',
);
}
logger.info?.(
{
event: 'skill-install.installed',
version: currentVersion,
hosts: hosts.map((h) => h.editorId),
paths: written.map((e) => e.path),
},
`OpenKnowledge skill installed to ${written.length} location(s): ${written
.map((e) => e.path)
.join(', ')}`,
);
await report('installed', currentVersion);
void reportSkillInstall(
{
source: OPENKNOWLEDGE_SKILLS_REPO,
skills: [bundleName],
agents: hosts.map((h) => h.editorId),
global: true,
version: currentVersion,
},
{ home, enabled: resolveSkillInstallReportSettings(home).enabled },
);
return 'installed';
}
const DOWNLOADS_DIR = 'Downloads';
const SKILL_FILENAME = 'openknowledge.skill';
export interface BuildAndOpenSkillOptions {
out?: string;
noOpen?: boolean;
force?: boolean;
spawnFn?: SpawnLike;
platformName?: NodeJS.Platform;
home?: string;
logger?: SkillInstallLogger;
}
export type BuildAndOpenSkillStatus = 'installed' | 'built' | 'failed' | 'skip-current';
export interface BuildAndOpenSkillResult {
status: BuildAndOpenSkillStatus;
outputPath?: string;
size?: number;
sha256?: string;
skillVersion?: string;
handoffError?: { reason: 'unsupported-platform' | 'spawn-error'; message: string };
buildError?: string;
recordedAt?: string;
}
function defaultDownloadsPath(home: string): string {
return join(home, DOWNLOADS_DIR, SKILL_FILENAME);
}
type FileAssociationOutcome =
| { ok: true }
| { ok: false; reason: 'unsupported-platform' | 'spawn-error'; message: string };
function fileAssociationCommand(
skillPath: string,
platformName: NodeJS.Platform,
): { command: string; args: string[] } | undefined {
if (platformName === 'darwin') return { command: 'open', args: [skillPath] };
if (platformName === 'win32') return { command: 'cmd', args: ['/c', 'start', '""', skillPath] };
if (platformName === 'linux') return { command: 'xdg-open', args: [skillPath] };
return undefined;
}
function spawnErrorOutcome(command: string, err: unknown): FileAssociationOutcome {
const detail = err instanceof Error ? err.message : String(err);
const missing = errnoCode(err) === 'ENOENT';
return {
ok: false,
reason: 'spawn-error',
message: missing ? `No system file opener (${command}) was found: ${detail}` : detail,
};
}
function invokeFileAssociation(
skillPath: string,
platformName: NodeJS.Platform,
spawnFn: SpawnLike,
): Promise<FileAssociationOutcome> {
const invocation = fileAssociationCommand(skillPath, platformName);
if (invocation === undefined) {
return Promise.resolve({
ok: false,
reason: 'unsupported-platform',
message: `Platform '${platformName}' has no file-association invocation wired.`,
});
}
const detached: SpawnOptions = withHiddenWindowsConsole({
detached: true,
stdio: 'ignore',
});
return new Promise((resolve) => {
let child: ReturnType<SpawnLike>;
try {
child = spawnFn(invocation.command, invocation.args, detached);
} catch (err) {
resolve(spawnErrorOutcome(invocation.command, err));
return;
}
child.on('error', (err) => resolve(spawnErrorOutcome(invocation.command, err)));
child.once('spawn', () => {
child.unref();
resolve({ ok: true });
});
});
}
export async function buildAndOpenSkill(
opts: BuildAndOpenSkillOptions = {},
): Promise<BuildAndOpenSkillResult> {
const home = opts.home ?? homedir();
const outputPath = resolvePath(opts.out ?? defaultDownloadsPath(home));
const platformName = opts.platformName ?? osPlatform();
const spawnFn = opts.spawnFn ?? spawn;
const logger = opts.logger;
const report = async (
outcome: SkillInstallEventOutcome,
version?: string,
reason?: string,
): Promise<void> => {
await recordSkillInstallEvent(
{
ts: new Date().toISOString(),
surface: 'server-build-and-open',
target: 'claude-cowork',
bundle: 'project',
outcome,
...(version !== undefined ? { version } : {}),
...(reason !== undefined ? { reason } : {}),
},
{ homedir: () => home, warn: logger?.warn },
);
};
if (!opts.force) {
let currentVersion: string | null = null;
try {
currentVersion = await readServerPackageVersion();
} catch (err) {
logger?.warn?.(
{ event: 'skill-install.gate.version-read-failed', err },
'Could not read @inkeep/open-knowledge-server version for gate check; rebuilding.',
);
}
if (currentVersion !== null) {
let recordedVersion: string | null = null;
let recordedAt: string | null = null;
try {
[recordedVersion, recordedAt] = await Promise.all([
readTargetVersion(home, 'claude-cowork', logger),
readTargetRecordedAt(home, 'claude-cowork', logger),
]);
} catch (err) {
logger?.warn?.(
{ event: 'skill-install.gate.read-failed', err },
'Could not read claude-cowork install-state; rebuilding.',
);
}
if (recordedVersion !== null && recordedVersion === currentVersion) {
logger?.info?.(
{
event: 'skill-install.skip-current',
target: 'claude-cowork',
version: currentVersion,
},
'OpenKnowledge skill already delivered at current version; skipping rebuild.',
);
await report('skip-current', currentVersion);
return {
status: 'skip-current',
skillVersion: currentVersion,
...(recordedAt !== null ? { recordedAt } : {}),
};
}
}
}
try {
await tracedMkdir(dirname(outputPath), { recursive: true });
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
await report('failed', undefined, `mkdir-failed:${message}`);
return {
status: 'failed',
buildError: `could not create output directory: ${message}`,
};
}
let build: BuildSkillZipResult;
try {
build = await buildSkillZip({ outputPath, bundle: 'project' });
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
await report('failed', undefined, `build-failed:${message}`);
return {
status: 'failed',
buildError: message,
};
}
let installedVersion: string | undefined;
try {
installedVersion = await readServerPackageVersion();
} catch {
installedVersion = undefined;
}
const baseResult: BuildAndOpenSkillResult = {
status: 'built',
outputPath: build.outputPath,
size: build.size,
sha256: build.sha256,
skillVersion: installedVersion,
};
if (installedVersion) {
try {
await writeTargetVersion(
home,
'claude-cowork',
installedVersion,
'server-build-and-open',
logger,
);
} catch (err) {
logger?.warn?.(
{
event: 'skill-install.state-write-failed',
target: 'claude-cowork',
version: installedVersion,
err,
},
'Skill bundle built but install-state write failed; gate will re-trigger build on next click.',
);
}
}
if (opts.noOpen) {
await report('built', installedVersion);
return baseResult;
}
const invocation = await invokeFileAssociation(build.outputPath, platformName, spawnFn);
if (!invocation.ok) {
await report('built', installedVersion, `handoff-${invocation.reason}`);
return {
...baseResult,
handoffError: { reason: invocation.reason, message: invocation.message },
};
}
await report('installed', installedVersion);
void reportSkillInstall(
{
source: OPENKNOWLEDGE_SKILLS_REPO,
skills: [BUNDLE_SKILL_NAME.project],
agents: ['claude-desktop'],
global: true,
version: installedVersion,
},
{ home, enabled: resolveSkillInstallReportSettings(home).enabled },
);
return { ...baseResult, status: 'installed' };
}