Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, mkdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
import { homedir } from 'node:os';
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
import { inspect } from 'node:util';
import {
CHECKOUT_CLI_COMMAND,
currentCliCommandName,
currentMcpServerName,
DESKTOP_PRODUCTS,
defaultToDevChannel,
isDevChannel,
type McpLauncherDeclineReason,
OPENKNOWLEDGE_SKILLS_REPO,
okUserHomeDisplayPath,
SKILL_STATE_FILENAME,
} from '@inkeep/open-knowledge-core';
import { atomicWriteFileSync, withFileLockSync } from '@inkeep/open-knowledge-core/server';
import type {
BundleId,
InstallUserSkillOptions,
InstallUserSkillResult,
} from '@inkeep/open-knowledge-server';
import {
BUNDLE_SKILL_NAME,
detectUserSkillHosts,
ensureProjectGit,
FilesystemRootProjectError,
GitNotAvailableError,
GitProbeTimeoutError,
GitTooOldError,
HomeProjectRootError,
initContent,
installUserSkill,
isFilesystemRoot,
isSkillInstallReportEnvOptOut,
ONBOARDING_BUNDLE_IDS,
ProjectGitInitError,
readBundleDecision,
removeProjectSkillGitignoreBlock,
reportSkillInstall,
resolveSkillInstallReportSettings,
USER_GLOBAL_BUNDLE_IDS,
writeBundleDecision,
writeRootGitignoreForNewRepo,
} from '@inkeep/open-knowledge-server';
import checkbox from '@inquirer/checkbox';
import select from '@inquirer/select';
import { Command, Option } from 'commander';
import {
applyEdits as applyJsoncEdits,
getNodeValue,
type Node as JsoncNode,
type ParseError as JsoncParseError,
modify as modifyJsonc,
parseTree as parseJsoncTree,
} from 'jsonc-parser';
import { stringify as stringifyToml } from 'smol-toml';
import { isCollection, parseDocument, stringify as stringifyYaml } from 'yaml';
import { CONFIG_FILENAME, OK_DIR } from '../constants.ts';
import { formatPreviewBlock, type PreviewResult } from '../content/preview.ts';
import { buildPiExtensionSource, makePiManagedFileEntry } from '../integrations/pi-extension.ts';
import {
isHomeDir,
type ResolveProjectRootResult,
resolveProjectRoot,
} from '../integrations/resolve-project-root.ts';
import {
assertProjectPathSafe,
type ProjectSkillResult,
writeProjectSkill,
writeProjectSkillToHub,
} from '../integrations/write-project-skill.ts';
import { debugNativeLoadFailure } from '../native/load-native-config.ts';
import { resolveHarnessWritePaths } from '../native/symlink-resolve.ts';
import {
getTomlConfigEngine,
type TomlConfigEngine,
type TomlUpsertResult,
} from '../native/toml-config-engine.ts';
import {
addOkPathsToGitExclude,
type ExcludeWriteResult,
getOkArtifactPaths,
readSharingMode,
removeOkPathsFromGitExclude,
type SharingMode,
type TrackedRefusal,
} from '../sharing/git-exclude.ts';
import { accent, dim, error, info, success, warning } from '../ui/colors.ts';
import {
type ConfigFileDeclineReason,
configFileDeclineReason,
} from '../utils/config-file-error.ts';
import { isObject } from '../utils/is-object.ts';
import {
ALL_EDITOR_IDS,
droppedManagedKeys,
EDITOR_LABELS,
EDITOR_TARGETS,
type EditorId,
type EditorMcpTarget,
entryCarriesOwnChain,
isOwnManagedEntry,
type McpInstallOptions,
managedEntryKeys,
resolveEditorTargets,
} from './editors.ts';
import { existingFileMode, isCrlfDominant } from './jsonc-surgical.ts';
const JSONC_PARSE_OPTIONS = { allowTrailingComma: true, disallowComments: false };
const JSONC_INVALID_SYMBOL_CODE: number = 1;
function isBenignBomError(error: JsoncParseError, raw: string): boolean {
return (
error.error === JSONC_INVALID_SYMBOL_CODE && error.offset === 0 && raw.charCodeAt(0) === 0xfeff
);
}
function parseJsoncObjectTree(raw: string): JsoncNode | null {
const errors: JsoncParseError[] = [];
const tree = parseJsoncTree(raw, errors, JSONC_PARSE_OPTIONS);
if (errors.some((error) => !isBenignBomError(error, raw))) return null;
if (tree?.type !== 'object') return null;
return tree;
}
function countTopLevelKey(objectNode: JsoncNode, key: string): number {
let count = 0;
for (const property of objectNode.children ?? []) {
const keyNode = property.children?.[0];
if (keyNode !== undefined && getNodeValue(keyNode) === key) count += 1;
}
return count;
}
function writeJsonConfig(path: string, config: Record<string, unknown>): void {
atomicWriteFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
}
function writeTomlConfig(path: string, config: Record<string, unknown>): void {
const serialized = stringifyToml(config);
atomicWriteFileSync(path, serialized.endsWith('\n') ? serialized : `${serialized}\n`);
}
function writeYamlConfig(path: string, config: Record<string, unknown>): void {
const serialized = stringifyYaml(config);
atomicWriteFileSync(path, serialized.endsWith('\n') ? serialized : `${serialized}\n`);
}
const JSON_CONFIG_MAX_BYTES = 10 * 1024 * 1024;
function jsonValueEqual(a: unknown, b: unknown): boolean {
if (a === b) return true;
if (Array.isArray(a) || Array.isArray(b)) {
if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
return a.every((value, index) => jsonValueEqual(value, b[index]));
}
if (isObject(a) && isObject(b)) {
const keys = Object.keys(a);
if (keys.length !== Object.keys(b).length) return false;
return keys.every((key) => Object.hasOwn(b, key) && jsonValueEqual(a[key], b[key]));
}
return false;
}
function managedEntryFieldsEqual(
existing: unknown,
desired: Record<string, unknown>,
keys: readonly string[],
): boolean {
return isObject(existing) && keys.every((key) => jsonValueEqual(existing[key], desired[key]));
}
function detectJsonIndent(body: string): { insertSpaces: boolean; tabSize: number } {
for (const line of body.split('\n')) {
const trimmed = line.trimStart();
if (trimmed.length === 0 || trimmed.length === line.length) continue;
if (line.charCodeAt(0) === 0x09) return { insertSpaces: false, tabSize: 1 };
return { insertSpaces: true, tabSize: line.length - trimmed.length };
}
return { insertSpaces: true, tabSize: 2 };
}
type JsonUpsertOutcome =
| { kind: 'written' | 'overwritten' | 'unchanged' }
| { kind: 'declined'; reason: McpWriteDeclineReason };
export function serverMapPath(
topLevelKey: string,
subKey: string | undefined,
serverName: string,
): string[] {
return subKey === undefined ? [topLevelKey, serverName] : [topLevelKey, subKey, serverName];
}
function freshServerMapObject(
topLevelKey: string,
subKey: string | undefined,
serverName: string,
entry: Record<string, unknown>,
): Record<string, unknown> {
const inner = { [serverName]: entry };
return { [topLevelKey]: subKey === undefined ? inner : { [subKey]: inner } };
}
function readServerContainer(
root: Record<string, unknown>,
topLevelKey: string,
subKey: string | undefined,
): unknown {
const top = root[topLevelKey];
if (subKey === undefined) return top;
return isObject(top) ? top[subKey] : undefined;
}
function upsertJsonMcpConfig(
configPath: string,
topLevelKey: string,
serverName: string,
entry: Record<string, unknown>,
subKey?: string,
replaceEntry = false,
pruneOnly = false,
): JsonUpsertOutcome {
if (!existsSync(configPath)) {
if (pruneOnly) return { kind: 'unchanged' };
writeJsonConfig(configPath, freshServerMapObject(topLevelKey, subKey, serverName, entry));
return { kind: 'written' };
}
let raw: string;
try {
raw = readFileSync(configPath, 'utf-8');
} catch (err) {
debugNativeLoadFailure('json config read failed', err);
return { kind: 'declined', reason: configFileDeclineReason(err) };
}
if (raw.trim() === '') {
if (pruneOnly) return { kind: 'unchanged' };
writeJsonConfig(configPath, freshServerMapObject(topLevelKey, subKey, serverName, entry));
return { kind: 'written' };
}
if (Buffer.byteLength(raw, 'utf-8') > JSON_CONFIG_MAX_BYTES) {
return { kind: 'declined', reason: 'oversize' };
}
const tree = parseJsoncObjectTree(raw);
if (!tree) return { kind: 'declined', reason: 'unparseable' };
if (countTopLevelKey(tree, topLevelKey) > 1) {
return { kind: 'declined', reason: 'duplicate-container' };
}
const root = getNodeValue(tree) as Record<string, unknown>;
const container = readServerContainer(root, topLevelKey, subKey);
const existing = isObject(container) ? container[serverName] : undefined;
const entryExists = existing !== undefined;
const managedKeys = managedEntryKeys(entry);
const exactMatch =
entryExists && replaceEntry
? isOwnManagedEntry(existing)
: entryExists && managedEntryFieldsEqual(existing, entry, managedKeys);
if (exactMatch) {
return { kind: pruneOnly ? 'unchanged' : 'overwritten' };
}
const hasBom = raw.charCodeAt(0) === 0xfeff;
const body = hasBom ? raw.slice(1) : raw;
const eol = body.includes('\r\n') ? '\r\n' : '\n';
const formattingOptions = { ...detectJsonIndent(body), eol };
const entryPath = serverMapPath(topLevelKey, subKey, serverName);
let editedBody = body;
if (pruneOnly) {
for (const key of entryExists ? droppedManagedKeys(existing, entry) : []) {
const edits = modifyJsonc(editedBody, [...entryPath, key], undefined, { formattingOptions });
editedBody = applyJsoncEdits(editedBody, edits);
}
} else if (entryExists && !replaceEntry && entryCarriesOwnChain(existing)) {
for (const key of managedKeys) {
const edits = modifyJsonc(editedBody, [...entryPath, key], entry[key], {
formattingOptions,
});
editedBody = applyJsoncEdits(editedBody, edits);
}
} else {
const edits = modifyJsonc(editedBody, entryPath, entry, { formattingOptions });
editedBody = applyJsoncEdits(editedBody, edits);
}
const newText = `${hasBom ? '\uFEFF' : ''}${editedBody}`;
if (newText !== raw) {
atomicWriteFileSync(configPath, newText, { mode: existingFileMode(configPath) });
}
if (pruneOnly && newText === raw) return { kind: 'unchanged' };
return { kind: entryExists ? 'overwritten' : 'written' };
}
type TomlUpsertOutcome =
| { kind: 'written' | 'overwritten' | 'unchanged' }
| { kind: 'declined'; reason: McpWriteDeclineReason };
function upsertTomlMcpConfig(
engine: TomlConfigEngine,
configPath: string,
topLevelKey: string,
serverName: string,
entry: Record<string, unknown>,
replaceEntry = false,
pruneOnly = false,
): TomlUpsertOutcome {
let raw = '';
if (existsSync(configPath)) {
try {
raw = readFileSync(configPath, 'utf-8');
} catch (err) {
debugNativeLoadFailure('toml config read failed', err);
return { kind: 'declined', reason: configFileDeclineReason(err) };
}
}
const blank = raw.trim() === '';
if (blank && pruneOnly) return { kind: 'unchanged' };
if (engine.backend === 'fallback') {
if (!blank) return { kind: 'declined', reason: 'no-native-writer' };
writeTomlConfig(configPath, { [topLevelKey]: { [serverName]: entry } });
return { kind: 'written' };
}
const hasBom = raw.charCodeAt(0) === 0xfeff;
const body = hasBom ? raw.slice(1) : raw;
const crlfDominant = isCrlfDominant(body);
const wantTrailingNewline = blank || body.endsWith('\n');
let result: TomlUpsertResult;
let replacing = false;
try {
const existing = existingTomlEntry(engine, body, topLevelKey, serverName);
if (pruneOnly) {
let pruned = body;
for (const key of existing === undefined ? [] : droppedManagedKeys(existing, entry)) {
pruned = engine.removeEntryKey(pruned, serverName, key).text;
}
result = { text: pruned, existed: existing !== undefined };
} else {
const plan = tomlWritePlan(existing, entry, replaceEntry);
replacing = plan.kind === 'replace';
let base = replacing ? engine.removeEntry(body, serverName).text : body;
if (plan.kind === 'merge') {
for (const key of plan.prune) base = engine.removeEntryKey(base, serverName, key).text;
}
result = engine.upsertEntry(base, serverName, entry);
}
} catch (err) {
debugNativeLoadFailure('upsertEntry failed', err);
return { kind: 'declined', reason: 'unparseable' };
}
let text = result.text;
if (wantTrailingNewline) {
if (!text.endsWith('\n')) text = `${text}\n`;
} else {
text = text.replace(/\n+$/, '');
}
if (crlfDominant) {
text = text.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
}
const newText = `${hasBom ? '\uFEFF' : ''}${text}`;
if (newText !== raw) {
atomicWriteFileSync(configPath, newText, { mode: existingFileMode(configPath) });
}
if (pruneOnly && newText === raw) return { kind: 'unchanged' };
return { kind: result.existed || replacing ? 'overwritten' : 'written' };
}
function existingTomlEntry(
engine: TomlConfigEngine,
body: string,
topLevelKey: string,
serverName: string,
): Record<string, unknown> | undefined {
if (body.trim() === '') return undefined;
const container = engine.parseToObject(body)[topLevelKey];
const existing = isObject(container) ? container[serverName] : undefined;
return isObject(existing) ? existing : undefined;
}
type TomlWritePlan = { kind: 'merge'; prune: readonly string[] } | { kind: 'replace' };
function tomlWritePlan(
existing: Record<string, unknown> | undefined,
entry: Record<string, unknown>,
replaceEntry: boolean,
): TomlWritePlan {
if (existing === undefined || isOwnManagedEntry(existing)) return { kind: 'merge', prune: [] };
if (replaceEntry || !entryCarriesOwnChain(existing)) return { kind: 'replace' };
return { kind: 'merge', prune: droppedManagedKeys(existing, entry) };
}
type YamlUpsertOutcome =
| { kind: 'written' | 'overwritten' | 'unchanged' }
| { kind: 'declined'; reason: McpWriteDeclineReason };
function upsertYamlMcpConfig(
configPath: string,
topLevelKey: string,
serverName: string,
entry: Record<string, unknown>,
replaceEntry = false,
pruneOnly = false,
): YamlUpsertOutcome {
let raw = '';
if (existsSync(configPath)) {
try {
raw = readFileSync(configPath, 'utf-8');
} catch (err) {
debugNativeLoadFailure('yaml config read failed', err);
return { kind: 'declined', reason: configFileDeclineReason(err) };
}
}
if (raw.trim() === '') {
if (pruneOnly) return { kind: 'unchanged' };
writeYamlConfig(configPath, { [topLevelKey]: { [serverName]: entry } });
return { kind: 'written' };
}
if (Buffer.byteLength(raw, 'utf-8') > JSON_CONFIG_MAX_BYTES) {
return { kind: 'declined', reason: 'oversize' };
}
const hasBom = raw.charCodeAt(0) === 0xfeff;
const body = hasBom ? raw.slice(1) : raw;
const doc = parseDocument(body);
if (doc.errors.length > 0) return { kind: 'declined', reason: 'unparseable' };
const path = [topLevelKey, serverName];
const entryExists = doc.hasIn(path);
if (doc.hasIn([topLevelKey]) && !isCollection(doc.getIn([topLevelKey], true))) {
doc.deleteIn([topLevelKey]);
}
const existingEntryNode = doc.getIn(path, true);
const mergeInPlace =
entryExists &&
isCollection(existingEntryNode) &&
(replaceEntry
? isOwnManagedEntry(existingEntryNode.toJSON())
: entryCarriesOwnChain(existingEntryNode.toJSON()));
if (pruneOnly) {
if (entryExists && isCollection(existingEntryNode)) {
for (const key of droppedManagedKeys(existingEntryNode.toJSON(), entry)) {
doc.deleteIn([...path, key]);
}
}
} else if (mergeInPlace) {
for (const key of managedEntryKeys(entry)) {
if (entry[key] === undefined) doc.deleteIn([...path, key]);
else doc.setIn([...path, key], doc.createNode(entry[key]));
}
} else {
doc.setIn(path, doc.createNode(entry));
}
let text = doc.toString();
const crlfDominant = isCrlfDominant(body);
const wantTrailingNewline = body.endsWith('\n');
if (wantTrailingNewline) {
if (!text.endsWith('\n')) text = `${text}\n`;
} else {
text = text.replace(/\n+$/, '');
}
if (crlfDominant) {
text = text.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
}
const newText = `${hasBom ? '\uFEFF' : ''}${text}`;
if (newText !== raw) {
atomicWriteFileSync(configPath, newText, { mode: existingFileMode(configPath) });
}
if (pruneOnly && newText === raw) return { kind: 'unchanged' };
return { kind: entryExists ? 'overwritten' : 'written' };
}
type McpScope = 'user' | 'project' | 'both';
const writesUser = (s: McpScope) => s !== 'project';
const writesProject = (s: McpScope) => s !== 'user';
async function promptMcpScope(): Promise<McpScope | null> {
const choices = await checkbox({
message: 'Where should the MCP server be configured?\n',
required: false,
theme: {
icon: {
checked: '[x]',
unchecked: '[ ]',
},
},
choices: [
{
name: 'User-level (~/.claude.json, ~/.cursor/mcp.json, …)',
value: 'user' as const,
checked: true,
},
{
name: 'Project-level (.mcp.json, .cursor/mcp.json, …)',
value: 'project' as const,
checked: true,
},
],
});
if (choices.includes('user') && choices.includes('project')) return 'both';
if (choices.includes('user')) return 'user';
if (choices.includes('project')) return 'project';
return null;
}
export async function resolveMcpScope(opts: {
scope?: McpScope;
mcp?: boolean;
isTTY?: boolean;
promptFn?: () => Promise<McpScope | null>;
}): Promise<McpScope | null> {
if (opts.mcp === false) return null;
if (opts.scope) return opts.scope;
const tty = opts.isTTY ?? process.stdout.isTTY;
if (!tty) return 'both';
const prompt = opts.promptFn ?? promptMcpScope;
return prompt();
}
async function promptSharingMode(
defaultMode: 'shared' | 'local-only',
): Promise<'shared' | 'local-only'> {
return select<'shared' | 'local-only'>({
message: 'How do you want to handle OpenKnowledge config files (.ok/, .mcp.json)?',
default: defaultMode,
choices: [
{
name: 'Share with my team (commit alongside content)',
value: 'shared',
description: 'OK config gets committed alongside your project content.',
},
{
name: 'Local only (keep out of git via .git/info/exclude)',
value: 'local-only',
description: `OK config stays on this machine only; teammates do not see it. Safe escape hatch via \`${currentCliCommandName()} config-sharing share\`.`,
},
],
});
}
export async function resolveSharingMode(opts: {
sharing?: 'shared' | 'local-only';
projectRoot: string;
isTTY?: boolean;
freshProject?: boolean;
promptFn?: (defaultMode: 'shared' | 'local-only') => Promise<'shared' | 'local-only'>;
}): Promise<'shared' | 'local-only'> {
if (opts.sharing !== undefined) return opts.sharing;
const current = readSharingMode(opts.projectRoot);
const seed: 'shared' | 'local-only' =
current === 'local-only' || opts.freshProject === true ? 'local-only' : 'shared';
const tty = opts.isTTY ?? process.stdout.isTTY;
if (!tty) return seed;
const prompt = opts.promptFn ?? promptSharingMode;
return prompt(seed);
}
export interface EditorMcpResult {
editorId: EditorId;
label: string;
action: 'written' | 'overwritten' | 'skipped-missing' | 'skipped-flag' | 'failed' | 'declined';
configPath: string;
serverName: string;
error?: string;
declineReason?: McpWriteDeclineReason;
configScope?: 'project';
}
interface ProjectConfigResult {
editorId: EditorId;
label: string;
path: string;
}
interface InitCommandOptions {
cwd?: string;
projectRootMode?: 'discover' | 'cwd';
mcp?: boolean;
devMcp?: boolean;
editors?: EditorId[];
home?: string;
installUserSkill?: (opts?: InstallUserSkillOptions) => Promise<InstallUserSkillResult>;
skills?: string | boolean;
scope?: McpScope;
isTTY?: boolean;
promptFn?: () => Promise<McpScope | null>;
sharing?: 'shared' | 'local-only';
sharingPromptFn?: (defaultMode: 'shared' | 'local-only') => Promise<'shared' | 'local-only'>;
contentDir?: string;
}
export class ContentDirError extends Error {
constructor(message: string) {
super(message);
this.name = 'ContentDirError';
}
}
export class DevMcpScopeError extends Error {
constructor(scope: McpScope) {
super(
`A dev MCP entry is written to project config only, never to user-level editor config, so --scope ${scope} is not supported with --dev-mcp or OK_CHANNEL=dev. Re-run with --scope project or without --scope.`,
);
this.name = 'DevMcpScopeError';
}
}
const DEV_CHANNEL_USER_MCP_REFUSAL = `A dev build registers OpenKnowledge MCP in project config only, never in user-level editor config. Run \`${CHECKOUT_CLI_COMMAND} init --dev-mcp\` in the project, or set OK_CHANNEL=stable.`;
export { FilesystemRootProjectError, HomeProjectRootError };
export function resolveInitSkillEnablement(skills: string | boolean | undefined): Set<BundleId> {
if (skills === undefined || skills === true) return new Set<BundleId>(ONBOARDING_BUNDLE_IDS);
if (skills === false) return new Set();
const requested = skills
.split(',')
.map((s) => s.trim())
.filter(Boolean);
return new Set(USER_GLOBAL_BUNDLE_IDS.filter((id) => requested.includes(id)));
}
export function resolveRequestedContentDir(
input: string,
projectRoot: string,
cwd: string,
): string {
const abs = resolve(cwd, input);
let stat: ReturnType<typeof statSync>;
try {
stat = statSync(abs);
} catch (e) {
const code = (e as NodeJS.ErrnoException).code;
if (code === 'ENOENT') {
throw new ContentDirError(`--content-dir path does not exist: ${abs}`);
}
throw new ContentDirError(
`--content-dir path is not accessible (${code ?? 'unknown error'}): ${abs}`,
);
}
if (!stat.isDirectory()) {
throw new ContentDirError(`--content-dir must be a directory: ${abs}`);
}
const canonRoot = safeRealpath(projectRoot);
const canonAbs = safeRealpath(abs);
const rel = relative(canonRoot, canonAbs);
if (rel.startsWith('..') || isAbsolute(rel)) {
throw new ContentDirError(
`--content-dir must be inside the project root (${projectRoot}); got ${abs}`,
);
}
return rel === '' ? '.' : rel;
}
function safeRealpath(p: string): string {
try {
return realpathSync(p);
} catch {
return p;
}
}
type InitSkillBundleResult = InstallUserSkillResult | 'opted-out' | 'decision-read-failed';
interface InitCommandResult {
projectRoot: string;
contentCreated: string[];
contentUpdated: string[];
contentSkipped: string[];
editors: EditorMcpResult[];
legacyProjectConfigs: ProjectConfigResult[];
projectSkills: ProjectSkillResult[];
skillInstall?: InitSkillBundleResult | 'declined';
skillBundles?: readonly { bundleId: BundleId; result: InitSkillBundleResult }[];
skillsRequested?: string | boolean;
skillHosts?: readonly string[];
skillInstallsCounted?: boolean;
preview?: PreviewResult;
didGitInit: boolean;
rootGitignoreCreated: boolean;
gitRootPromoted: boolean;
promotedFromDir?: string;
contentDir?: string;
contentDirRequested?: string;
contentScaffoldFailed: boolean;
mcpAction: 'written' | 'overwritten' | 'skipped-missing' | 'skipped-flag' | 'failed' | 'declined';
mcpPath: string;
mcpError?: string;
previewWarning?: string;
projectScopeUnsupportedLabels?: string[];
sharing: SharingOutcome;
}
export type SharingOutcome =
| {
kind: 'applied';
mode: SharingMode;
action: 'added' | 'removed' | 'cleaned' | 'noop';
appended: string[];
alreadyPresent: string[];
removed: string[];
}
| { kind: 'refused-tracked'; tracked: string[]; remediation: string }
| {
kind: 'no-exclude';
reason: 'no-git' | 'no-info-dir' | 'malformed-pointer' | 'inaccessible';
localOnlyRequested: boolean;
};
export const LAUNCH_CONFIG_NAME = 'open-knowledge-ui';
export function isEditorTargetAvailable(
target: EditorMcpTarget,
cwd: string,
home?: string,
): boolean {
try {
const probePath = target.detectPath?.(cwd, home) ?? dirname(target.configPath(cwd, home));
return existsSync(probePath);
} catch {
return false;
}
}
export function writeWouldFabricateDetection(
target: EditorMcpTarget,
cwd: string,
home?: string,
): boolean {
try {
const configDir = resolve(dirname(target.configPath(cwd, home)));
const probePath = resolve(target.detectPath?.(cwd, home) ?? configDir);
return probePath === configDir || configDir.startsWith(probePath + sep);
} catch {
return false;
}
}
export function writeEditorMcpConfig(
target: EditorMcpTarget,
cwd: string,
installOptions: McpInstallOptions,
home?: string,
configPathOverride?: string,
): EditorMcpResult {
const serverName = target.serverName(cwd);
let configPath: string;
try {
configPath = configPathOverride ?? target.configPath(cwd, home);
} catch (err) {
return {
editorId: target.id,
label: target.label,
action: 'failed',
configPath: '',
serverName,
error: err instanceof Error ? err.message : String(err),
};
}
const pruneOnly = installOptions.pruneOnly === true;
if (pruneOnly && (target.format === 'file' || !existsSync(configPath))) {
return {
editorId: target.id,
label: target.label,
action: 'skipped-flag',
configPath,
serverName,
...(configPathOverride !== undefined ? { configScope: 'project' as const } : {}),
};
}
const enforceAvailability =
!installOptions.skipAvailabilityCheck ||
target.offerOnlyWhenDetected === true ||
writeWouldFabricateDetection(target, cwd, home);
if (!configPathOverride && enforceAvailability && !isEditorTargetAvailable(target, cwd, home)) {
return {
editorId: target.id,
label: target.label,
action: 'skipped-missing',
configPath,
serverName,
};
}
if (configPathOverride !== undefined) {
try {
assertProjectPathSafe(configPath, cwd);
} catch (err) {
return {
editorId: target.id,
label: target.label,
action: 'failed',
configPath,
serverName,
error: err instanceof Error ? err.message : String(err),
configScope: 'project' as const,
};
}
}
if (target.format === 'file') {
return writeManagedEditorFile(target, configPath, serverName, installOptions, {
isProjectScope: configPathOverride !== undefined,
});
}
let targetEntry: Record<string, unknown>;
try {
targetEntry = target.buildEntry(cwd, installOptions);
} catch (err) {
return {
editorId: target.id,
label: target.label,
action: 'failed',
configPath,
serverName,
error: err instanceof Error ? err.message : String(err),
...(configPathOverride !== undefined ? { configScope: 'project' as const } : {}),
};
}
try {
if (!pruneOnly) mkdirSync(dirname(configPath), { recursive: true });
} catch (err) {
return {
editorId: target.id,
label: target.label,
action: 'failed',
configPath,
serverName,
error: err instanceof Error ? err.message : String(err),
...(configPathOverride !== undefined ? { configScope: 'project' as const } : {}),
};
}
const captured: {
action: 'written' | 'overwritten' | 'unchanged' | 'declined';
declineReason?: McpWriteDeclineReason;
} = { action: 'written' };
let lockErr: Error | undefined;
try {
withFileLockSync(
`${configPath}.lock`,
() => {
const writePath = resolveHarnessWritePaths(configPath).writePath;
if (!pruneOnly) mkdirSync(dirname(writePath), { recursive: true });
if (target.format === 'toml') {
const tomlOutcome = upsertTomlMcpConfig(
getTomlConfigEngine(),
writePath,
target.topLevelKey,
serverName,
targetEntry,
installOptions.replaceEntry === true,
installOptions.pruneOnly === true,
);
captured.action = tomlOutcome.kind;
if (tomlOutcome.kind === 'declined') captured.declineReason = tomlOutcome.reason;
return;
}
if (target.format === 'yaml') {
const yamlOutcome = upsertYamlMcpConfig(
writePath,
target.topLevelKey,
serverName,
targetEntry,
installOptions.replaceEntry === true,
installOptions.pruneOnly === true,
);
captured.action = yamlOutcome.kind;
if (yamlOutcome.kind === 'declined') captured.declineReason = yamlOutcome.reason;
return;
}
const outcome = upsertJsonMcpConfig(
writePath,
target.topLevelKey,
serverName,
targetEntry,
target.serverMapSubKey,
installOptions.replaceEntry === true,
installOptions.pruneOnly === true,
);
captured.action = outcome.kind;
if (outcome.kind === 'declined') captured.declineReason = outcome.reason;
},
{
onWarn: (message, context) =>
process.stderr.write(`[ok] ${message} ${JSON.stringify(context)}\n`),
},
);
} catch (err) {
lockErr = err instanceof Error ? err : new Error(String(err));
}
if (lockErr) {
return {
editorId: target.id,
label: target.label,
action: 'failed',
configPath,
serverName,
error: lockErr.message,
...(configPathOverride !== undefined ? { configScope: 'project' as const } : {}),
};
}
if (captured.action === 'declined') {
return {
editorId: target.id,
label: target.label,
action: 'declined',
configPath,
serverName,
declineReason: captured.declineReason,
...(configPathOverride !== undefined ? { configScope: 'project' as const } : {}),
};
}
return {
editorId: target.id,
label: target.label,
action: captured.action === 'unchanged' ? 'skipped-flag' : captured.action,
configPath,
serverName,
...(configPathOverride !== undefined ? { configScope: 'project' as const } : {}),
};
}
export const MANAGED_FILE_BUILDERS: Partial<
Record<EditorId, (options?: McpInstallOptions) => string>
> = {
pi: buildPiExtensionSource,
};
function writeManagedEditorFile(
target: EditorMcpTarget,
configPath: string,
serverName: string,
installOptions: McpInstallOptions,
opts: { isProjectScope: boolean },
): EditorMcpResult {
const scopeField = opts.isProjectScope ? { configScope: 'project' as const } : {};
const fail = (err: unknown): EditorMcpResult => ({
editorId: target.id,
label: target.label,
action: 'failed',
configPath,
serverName,
error: err instanceof Error ? err.message : String(err),
...scopeField,
});
const buildFileContent = MANAGED_FILE_BUILDERS[target.id];
if (!buildFileContent) {
return fail(
new Error(
`No managed-file builder registered for editor "${target.id}" (format: 'file' targets need a MANAGED_FILE_BUILDERS entry).`,
),
);
}
let desired: string;
try {
desired = buildFileContent(installOptions);
} catch (err) {
return fail(err);
}
try {
mkdirSync(dirname(configPath), { recursive: true });
} catch (err) {
return fail(err);
}
const captured: { action: 'written' | 'overwritten' } = { action: 'written' };
try {
withFileLockSync(
`${configPath}.lock`,
() => {
let existing: string | null = null;
try {
existing = readFileSync(configPath, 'utf-8');
} catch {
existing = null;
}
if (existing === desired) {
captured.action = 'overwritten';
return;
}
atomicWriteFileSync(
configPath,
desired,
existing !== null ? { mode: existingFileMode(configPath) } : undefined,
);
captured.action = existing === null ? 'written' : 'overwritten';
},
{
onWarn: (message, context) =>
process.stderr.write(`[ok] ${message} ${JSON.stringify(context)}\n`),
},
);
} catch (err) {
return fail(err);
}
return {
editorId: target.id,
label: target.label,
action: captured.action,
configPath,
serverName,
...scopeField,
};
}
function collectProjectConfig(
target: EditorMcpTarget,
cwd: string,
): ProjectConfigResult | undefined {
const projectPath = target.projectConfigPath?.(cwd);
if (!projectPath || !existsSync(projectPath)) return undefined;
return {
editorId: target.id,
label: target.label,
path: projectPath,
};
}
export interface UserMcpConfigsOptions {
editors: EditorId[];
home?: string;
replaceEntry?: boolean;
pruneOnly?: boolean;
}
export async function writeUserMcpConfigs(opts: UserMcpConfigsOptions): Promise<EditorMcpResult[]> {
const targets = resolveEditorTargets(opts.editors).filter((t) => t.scope === 'global');
if (isDevChannel()) {
return targets.map((target) => ({
editorId: target.id,
label: target.label,
action: 'failed',
configPath: target.configPath('', opts.home),
serverName: target.serverName(''),
error: DEV_CHANNEL_USER_MCP_REFUSAL,
}));
}
const installOptions: McpInstallOptions = {
mode: 'published',
skipAvailabilityCheck: true,
...(opts.replaceEntry === true ? { replaceEntry: true } : {}),
...(opts.pruneOnly === true ? { pruneOnly: true } : {}),
};
return targets.map((target) => writeEditorMcpConfig(target, '', installOptions, opts.home));
}
export function readExistingMcpEntry(
target: EditorMcpTarget,
cwd: string,
home?: string,
configPathOverride?: string,
): Record<string, unknown> | null {
const classified = classifyExistingMcpEntry(target, cwd, home, configPathOverride);
return classified.kind === 'present' ? classified.entry : null;
}
export type McpConfigDeclineReason =
| ConfigFileDeclineReason
| 'unparseable'
| 'duplicate-container'
| 'oversize'
| 'no-native-writer';
export type McpDeclineReason = McpConfigDeclineReason | McpLauncherDeclineReason;
type McpWriteDeclineReason = Exclude<McpConfigDeclineReason, 'missing-symlink-target'>;
export type McpEntryClassification =
| { kind: 'absent' }
| { kind: 'no-entry' }
| { kind: 'present'; entry: Record<string, unknown> }
| { kind: 'decline'; reason: McpConfigDeclineReason };
function classifyContainer(
config: Record<string, unknown>,
topLevelKey: string,
serverName: string,
subKey?: string,
): McpEntryClassification {
const servers = readServerContainer(config, topLevelKey, subKey);
if (!isObject(servers)) return { kind: 'no-entry' };
const existing = servers[serverName];
if (!isObject(existing)) return { kind: 'no-entry' };
return { kind: 'present', entry: existing };
}
export function classifyExistingMcpEntry(
target: EditorMcpTarget,
cwd: string,
home?: string,
configPathOverride?: string,
): McpEntryClassification {
let configPath: string;
try {
configPath = configPathOverride ?? target.configPath(cwd, home);
} catch {
return { kind: 'absent' };
}
if (!existsSync(configPath)) return { kind: 'absent' };
try {
if (statSync(configPath).size > JSON_CONFIG_MAX_BYTES) {
return { kind: 'decline', reason: 'oversize' };
}
} catch (error) {
return { kind: 'decline', reason: configFileDeclineReason(error) };
}
let raw: string;
try {
raw = readFileSync(configPath, 'utf-8');
} catch (error) {
return { kind: 'decline', reason: configFileDeclineReason(error) };
}
if (raw.trim() === '') {
return { kind: 'absent' };
}
if (target.format === 'file') {
return { kind: 'present', entry: makePiManagedFileEntry(raw) };
}
const serverName = target.serverName(cwd);
if (target.format === 'toml') {
let config: Record<string, unknown>;
try {
config = getTomlConfigEngine().parseToObject(raw);
} catch {
return { kind: 'decline', reason: 'unparseable' };
}
return classifyContainer(config, target.topLevelKey, serverName, target.serverMapSubKey);
}
if (target.format === 'yaml') {
const doc = parseDocument(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
if (doc.errors.length > 0) return { kind: 'decline', reason: 'unparseable' };
const config = (doc.toJS() ?? {}) as Record<string, unknown>;
return classifyContainer(config, target.topLevelKey, serverName, target.serverMapSubKey);
}
const tree = parseJsoncObjectTree(raw);
if (!tree) return { kind: 'decline', reason: 'unparseable' };
if (countTopLevelKey(tree, target.topLevelKey) > 1) {
return { kind: 'decline', reason: 'duplicate-container' };
}
return classifyContainer(
getNodeValue(tree) as Record<string, unknown>,
target.topLevelKey,
serverName,
target.serverMapSubKey,
);
}
export async function runInit(options: InitCommandOptions = {}): Promise<InitCommandResult> {
const cwd = resolve(options.cwd ?? process.cwd());
const resolution =
options.projectRootMode === 'cwd'
? ({
projectRoot: cwd,
defaultContentDir: '.',
ancestorPromoted: false,
gitRootPromoted: false,
} satisfies ResolveProjectRootResult)
: resolveProjectRoot(cwd, { homeDir: options.home });
const projectRoot = resolution.projectRoot;
if (isHomeDir(projectRoot, options.home ?? homedir())) {
throw new HomeProjectRootError(projectRoot);
}
if (isFilesystemRoot(projectRoot)) {
throw new FilesystemRootProjectError(projectRoot);
}
const willScaffold = !existsSync(join(projectRoot, OK_DIR));
const promotedFromDir = resolution.gitRootPromoted ? relative(projectRoot, cwd) : undefined;
const contentDirScope =
options.contentDir !== undefined
? resolveRequestedContentDir(options.contentDir, projectRoot, cwd)
: resolution.defaultContentDir;
if (resolution.ancestorPromoted) {
console.log(`[ok] Opened existing project at ${projectRoot}`);
} else if (resolution.gitRootPromoted && willScaffold && contentDirScope === '.') {
process.stderr.write(
`${warning(`[ok] Content scope promoted to the git repo root: ${projectRoot}`)}\n` +
` Ran in ${promotedFromDir}/, but .ok/ lives at the git root (one .ok/ per git repo),\n` +
` so the whole repo is now the content scope. To narrow it, re-run with\n` +
` \`${currentCliCommandName()} init --content-dir .\`, or set content.dir: ${promotedFromDir} in ${OK_DIR}/config.yml.\n`,
);
}
const installOptions: McpInstallOptions = {
mode: options.devMcp ? 'dev' : 'published',
};
const projectOnlyMcp = options.devMcp === true || isDevChannel();
if (projectOnlyMcp && options.mcp !== false && options.scope && options.scope !== 'project') {
throw new DevMcpScopeError(options.scope);
}
const gitResult = await ensureProjectGit(projectRoot);
let contentResult: ReturnType<typeof initContent>;
try {
contentResult = initContent(projectRoot, { contentDir: contentDirScope });
} catch (err) {
const fallbackPath = EDITOR_TARGETS.claude.configPath(projectRoot, options.home);
return {
projectRoot,
contentCreated: [],
contentUpdated: [],
contentSkipped: [],
editors: [],
projectSkills: [],
legacyProjectConfigs: [],
didGitInit: gitResult.didInit,
rootGitignoreCreated: false,
gitRootPromoted: resolution.gitRootPromoted,
promotedFromDir,
contentDirRequested: options.contentDir,
contentScaffoldFailed: true,
mcpAction: 'failed',
mcpPath: fallbackPath,
mcpError: `Content scaffolding failed: ${err instanceof Error ? err.message : String(err)}`,
sharing: { kind: 'no-exclude', reason: 'no-git', localOnlyRequested: false },
};
}
const configCreated = contentResult.created.includes(CONFIG_FILENAME);
let rootGitignoreCreated = false;
if (gitResult.didInit) {
try {
rootGitignoreCreated = writeRootGitignoreForNewRepo(projectRoot) === 'created';
} catch (err) {
console.warn(
`[ok] Skipping .gitignore seed at ${projectRoot}: ${err instanceof Error ? err.message : String(err)}`,
);
}
}
try {
if (removeProjectSkillGitignoreBlock(projectRoot) === 'removed') {
console.warn(
'[ok] Removed the OpenKnowledge project-skill lines from .gitignore. The skill is ordinary project content now — commit it if your team wants it on clone.',
);
}
} catch (err) {
console.warn(
`[ok] Skipping project-skill .gitignore cleanup at ${projectRoot}: ${err instanceof Error ? err.message : String(err)}`,
);
}
const scope = await resolveMcpScope({
scope: projectOnlyMcp ? 'project' : options.scope,
mcp: options.mcp,
isTTY: options.isTTY,
promptFn: options.promptFn,
});
const userEditorIds = options.editors ?? detectInstalledEditors(projectRoot, options.home);
const projectEditorIds = options.editors ?? userEditorIds;
const userTargets = resolveEditorTargets(userEditorIds as EditorId[]);
const projectTargets = resolveEditorTargets(projectEditorIds as EditorId[]);
const skipMcp = options.mcp === false || scope === null;
const selectedTargets = Array.from(
new Map(
[...userTargets, ...(skipMcp ? [] : projectTargets)].map((target) => [target.id, target]),
).values(),
);
const availableTargets = userTargets.filter((target) =>
isEditorTargetAvailable(target, projectRoot, options.home),
);
const editorResults: EditorMcpResult[] = [];
const projectSkillResults: ProjectSkillResult[] = [];
const writtenProjectPaths = new Set<string>();
for (const target of selectedTargets) {
if (skipMcp) {
let configPath = '';
try {
configPath = target.configPath(projectRoot, options.home);
} catch {}
editorResults.push({
editorId: target.id,
label: target.label,
action: 'skipped-flag',
configPath,
serverName: target.serverName(projectRoot),
});
continue;
}
if (writesUser(scope) && userTargets.includes(target) && target.scope === 'global') {
editorResults.push(writeEditorMcpConfig(target, projectRoot, installOptions, options.home));
}
if (writesProject(scope) && projectTargets.includes(target) && target.projectConfigPath) {
const projPath = target.projectConfigPath(projectRoot);
const projResult = writeEditorMcpConfig(
target,
projectRoot,
installOptions,
options.home,
projPath,
);
editorResults.push(projResult);
if (projResult.action === 'written' || projResult.action === 'overwritten') {
writtenProjectPaths.add(projPath);
}
}
}
const writtenSkillPaths = new Set<string>();
for (const target of projectTargets) {
const skillPath = target.projectSkillPath?.(projectRoot);
if (!skillPath || writtenSkillPaths.has(skillPath)) continue;
writtenSkillPaths.add(skillPath);
projectSkillResults.push(writeProjectSkill(target, projectRoot, { home: options.home }));
}
const hubSkill = writeProjectSkillToHub(
projectRoot,
projectTargets.map((t) => t.id),
);
if (hubSkill) projectSkillResults.push(hubSkill);
const installedForEditors = projectSkillResults
.filter((r) => r.action === 'written' || r.action === 'overwritten')
.map((r) => r.editorId);
if (installedForEditors.length > 0) {
const reportHome = options.home ?? homedir();
void reportSkillInstall(
{
source: OPENKNOWLEDGE_SKILLS_REPO,
skills: [BUNDLE_SKILL_NAME.project],
agents: installedForEditors,
scope: projectRoot,
},
{ home: reportHome, enabled: resolveSkillInstallReportSettings(reportHome).enabled },
);
}
const projectScopeUnsupportedLabels =
!skipMcp && scope !== null && writesProject(scope)
? projectTargets
.filter((t) => !t.projectConfigPath && !t.projectSkillPath)
.map((t) => t.label)
: undefined;
const legacyProjectConfigs = skipMcp
? []
: availableTargets
.map((target) => collectProjectConfig(target, projectRoot))
.filter((result): result is ProjectConfigResult => result !== undefined)
.filter((result) => !writtenProjectPaths.has(result.path));
const installSkill = options.installUserSkill ?? installUserSkill;
const skillHome = options.home ?? homedir();
const enabledBundles = resolveInitSkillEnablement(options.skills);
const honorsRecordedOptOut = typeof options.skills !== 'string';
let anyEnabled = false;
let anyInstalled = false;
let anyFailed = false;
let anySkipped = false;
let anyNoHosts = false;
let anyOptedOut = false;
let anyDecisionReadFailed = false;
const skillBundles: { bundleId: BundleId; result: InitSkillBundleResult }[] = [];
for (const id of USER_GLOBAL_BUNDLE_IDS) {
if (!enabledBundles.has(id)) continue;
anyEnabled = true;
if (honorsRecordedOptOut) {
const decision = await readBundleDecision(skillHome, BUNDLE_SKILL_NAME[id]).then(
(value) => ({ ok: true as const, value }),
() => ({ ok: false as const }),
);
if (!decision.ok) {
skillBundles.push({ bundleId: id, result: 'decision-read-failed' });
anyDecisionReadFailed = true;
continue;
}
if (decision.value === false) {
skillBundles.push({ bundleId: id, result: 'opted-out' });
anyOptedOut = true;
continue;
}
}
await writeBundleDecision(skillHome, BUNDLE_SKILL_NAME[id], true).catch(() => {});
const result = await installSkill({ home: options.home, bundleId: id, force: true });
skillBundles.push({ bundleId: id, result });
if (result === 'installed') anyInstalled = true;
else if (result === 'failed') anyFailed = true;
else if (result === 'no-hosts') anyNoHosts = true;
else anySkipped = true;
}
const skillInstall: InitSkillBundleResult | 'declined' = anyFailed
? 'failed'
: anyDecisionReadFailed
? 'decision-read-failed'
: anyInstalled
? 'installed'
: anyEnabled && anySkipped
? 'skip-current'
: anyEnabled && anyNoHosts
? 'no-hosts'
: anyOptedOut
? 'opted-out'
: 'declined';
const skillHosts = anyInstalled ? detectUserSkillHosts(skillHome).map((h) => h.editorId) : [];
const skillInstallsCounted =
resolveSkillInstallReportSettings(skillHome).enabled && !isSkillInstallReportEnvOptOut();
const defaultAction: EditorMcpResult['action'] = skipMcp ? 'skipped-flag' : 'skipped-missing';
const primary = editorResults.find((r) => r.editorId === 'claude') ??
editorResults[0] ?? {
action: defaultAction,
configPath: EDITOR_TARGETS.claude.configPath(projectRoot, options.home),
};
const desiredMode = await resolveSharingMode({
sharing: options.sharing,
projectRoot,
isTTY: options.isTTY,
freshProject: willScaffold,
promptFn: options.sharingPromptFn,
});
const sharing = await applySharingMode({
projectRoot,
desiredMode,
explicitFlag: options.sharing,
});
return {
projectRoot,
contentCreated: contentResult.created,
contentUpdated: contentResult.updated,
contentSkipped: contentResult.skipped,
editors: editorResults,
projectSkills: projectSkillResults,
legacyProjectConfigs,
skillInstall,
skillBundles,
skillsRequested: options.skills,
skillHosts,
skillInstallsCounted,
didGitInit: gitResult.didInit,
rootGitignoreCreated,
gitRootPromoted: resolution.gitRootPromoted,
promotedFromDir,
contentDir: configCreated ? contentDirScope : undefined,
contentDirRequested: options.contentDir,
contentScaffoldFailed: false,
mcpAction: primary.action,
mcpPath: primary.configPath,
mcpError: 'error' in primary ? (primary as EditorMcpResult).error : undefined,
projectScopeUnsupportedLabels,
sharing,
};
}
export async function applySharingMode(opts: {
projectRoot: string;
desiredMode: 'shared' | 'local-only';
explicitFlag: 'shared' | 'local-only' | undefined;
}): Promise<SharingOutcome> {
const { projectRoot, desiredMode, explicitFlag } = opts;
const current = readSharingMode(projectRoot);
if (current === 'no-git') {
return {
kind: 'no-exclude',
reason: 'no-git',
localOnlyRequested: explicitFlag === 'local-only',
};
}
const paths = getOkArtifactPaths(projectRoot);
if (desiredMode === 'local-only') {
const result = addOkPathsToGitExclude(projectRoot, paths);
if (result.kind === 'refused-tracked') {
const refusal: TrackedRefusal = result;
return {
kind: 'refused-tracked',
tracked: refusal.tracked,
remediation: refusal.remediation,
};
}
if (result.kind === 'no-exclude') {
return {
kind: 'no-exclude',
reason: result.reason,
localOnlyRequested: explicitFlag === 'local-only',
};
}
return summarizeApplied(projectRoot, result, 'add');
}
if (current === 'shared') {
return {
kind: 'applied',
mode: 'shared',
action: 'noop',
appended: [],
alreadyPresent: [],
removed: [],
};
}
const result = removeOkPathsFromGitExclude(projectRoot, paths);
if (result.kind === 'no-exclude') {
return {
kind: 'no-exclude',
reason: result.reason,
localOnlyRequested: false,
};
}
return summarizeApplied(projectRoot, result, 'remove');
}
function summarizeApplied(
projectRoot: string,
result: Extract<ExcludeWriteResult, { kind: 'updated' }>,
direction: 'add' | 'remove',
): Extract<SharingOutcome, { kind: 'applied' }> {
const mode = readSharingMode(projectRoot);
if (direction === 'add') {
return {
kind: 'applied',
mode,
action: result.appended.length > 0 ? 'added' : result.removed.length > 0 ? 'cleaned' : 'noop',
appended: result.appended,
alreadyPresent: result.alreadyPresent,
removed: result.removed,
};
}
return {
kind: 'applied',
mode,
action: 'removed',
appended: [],
alreadyPresent: [],
removed: result.removed,
};
}
function declineReasonLabel(reason: McpWriteDeclineReason | undefined): string {
switch (reason) {
case 'permission-denied':
return 'permission denied; check file and parent-directory permissions';
case 'unresolved-symlink':
return 'could not resolve the path or symlink; check permissions and symlink cycles';
case 'not-a-file':
return 'config path is not a regular file';
case 'disappeared':
return 'config disappeared while being read; retry to check its current state';
case 'unreadable':
return 'could not read the config file; check that the path is accessible';
case 'unparseable':
return 'config could not be parsed';
case 'oversize':
return 'config too large to edit safely';
case 'duplicate-container':
return 'duplicate server block';
case 'no-native-writer':
return 'no format-preserving writer available';
case undefined:
return 'config not readable';
default: {
const exhaustive: never = reason;
throw new Error(`unhandled MCP decline reason: ${exhaustive}`);
}
}
}
export function formatInitResult(result: InitCommandResult, cwd: string): string {
const lines: string[] = [];
const anyWritten = result.editors.some(
(e) => e.action === 'written' || e.action === 'overwritten',
);
const anyFailed =
result.editors.some((e) => e.action === 'failed') ||
result.projectSkills.some((skill) => skill.action === 'failed');
const allSkippedFlag =
result.editors.length > 0 && result.editors.every((e) => e.action === 'skipped-flag');
const allSkippedMissing =
result.editors.length > 0 && result.editors.every((e) => e.action === 'skipped-missing');
if (result.didGitInit) {
lines.push(`Initialized git repo at ${cwd}/.git/`);
}
if (result.rootGitignoreCreated) {
lines.push(`Seeded .gitignore at ${cwd}/.gitignore (.DS_Store)`);
}
const okDir = join(cwd, OK_DIR);
if (result.contentCreated.length > 0 || result.contentUpdated.length > 0) {
lines.push(accent(`Content scaffolded at ${okDir}/`));
if (result.contentCreated.length > 0) {
lines.push(` Created: ${result.contentCreated.join(', ')}`);
}
if (result.contentUpdated.length > 0) {
lines.push(` Updated: ${result.contentUpdated.join(', ')}`);
}
} else {
lines.push(accent(`Content already present at ${okDir}/`));
}
if (result.contentSkipped.length > 0) {
lines.push(` Skipped (already exist): ${result.contentSkipped.join(', ')}`);
}
lines.push('');
if (result.mcpError && result.editors.length === 0) {
lines.push(`Warning: ${result.mcpError}`);
} else if (result.editors.length === 0) {
lines.push(accent('MCP server configuration:'));
if (result.mcpAction === 'skipped-flag') {
lines.push(' MCP config not written — use without --no-mcp to configure editors');
} else if (
result.projectScopeUnsupportedLabels &&
result.projectScopeUnsupportedLabels.length > 0
) {
const names = result.projectScopeUnsupportedLabels.join(', ');
const verb = result.projectScopeUnsupportedLabels.length === 1 ? 'does' : 'do';
lines.push(` ${names} ${verb} not support project-level config; skipped`);
} else {
lines.push(' No supported editor config directories detected; skipped MCP registration');
}
} else if (allSkippedFlag) {
lines.push('MCP config not written — use without --no-mcp to configure editors');
} else if (allSkippedMissing) {
lines.push(accent('MCP server configuration:'));
lines.push(' No supported editor config directories detected; skipped MCP registration');
} else {
lines.push(accent('MCP server configuration:'));
for (const editor of result.editors) {
const displayPath = editor.configPath.startsWith(cwd)
? relative(cwd, editor.configPath)
: editor.configPath.replace(/^\/Users\/[^/]+/, '~');
const serverNameNote =
editor.serverName === currentMcpServerName() ? '' : ` (${editor.serverName})`;
const scopeTag = editor.configScope === 'project' ? ' (project)' : '';
const labelWithScope = `${editor.label}${scopeTag}`;
const pad = ' '.repeat(Math.max(1, 20 - labelWithScope.length));
const restartHint =
editor.editorId === 'claude-desktop' &&
(editor.action === 'written' || editor.action === 'overwritten')
? ' — quit and relaunch Claude Desktop to activate'
: '';
switch (editor.action) {
case 'written':
lines.push(
` ${labelWithScope}${pad}${displayPath} ${success('registered')}${serverNameNote}${restartHint}`,
);
break;
case 'overwritten':
lines.push(
` ${labelWithScope}${pad}${displayPath} ${success('updated')}${serverNameNote}${restartHint}`,
);
break;
case 'skipped-missing':
lines.push(` ${labelWithScope}${pad}${displayPath} config root missing; skipped`);
break;
case 'failed':
lines.push(
` ${labelWithScope}${pad}${displayPath} ${error('FAILED')}: ${editor.error}`,
);
break;
case 'declined':
lines.push(
` ${labelWithScope}${pad}${displayPath} left unchanged (${declineReasonLabel(editor.declineReason)})`,
);
break;
case 'skipped-flag':
break;
default: {
const _exhaustive: never = editor.action;
void _exhaustive;
}
}
}
if (result.projectScopeUnsupportedLabels && result.projectScopeUnsupportedLabels.length > 0) {
const names = result.projectScopeUnsupportedLabels.join(', ');
const verb = result.projectScopeUnsupportedLabels.length === 1 ? 'does' : 'do';
lines.push(` ${names} ${verb} not support project-level config; skipped`);
}
const devServerName = DESKTOP_PRODUCTS.dev.mcpServerName;
if (
result.editors.some(
(e) =>
e.serverName === devServerName && (e.action === 'written' || e.action === 'overwritten'),
)
) {
lines.push(
` The ${devServerName} entry runs this checkout on this machine only; keep it out of commits.`,
);
}
}
if (result.projectSkills.length > 0) {
lines.push('');
lines.push(accent('Project-local skills:'));
for (const skill of result.projectSkills) {
const label = `${skill.label} (project)`;
const pad = ' '.repeat(Math.max(1, 20 - label.length));
const displayPath = skill.path ? relative(cwd, skill.path) : '';
switch (skill.action) {
case 'written':
lines.push(` ${label}${pad}${displayPath} ${success('installed')}`);
break;
case 'overwritten':
lines.push(` ${label}${pad}${displayPath} ${success('updated')}`);
break;
case 'skipped-unsupported':
lines.push(` ${label}${pad}no known project skill surface; skipped`);
break;
case 'skipped-prerequisite':
lines.push(` ${label}${pad}OpenKnowledge MCP is not configured; skipped`);
break;
case 'failed':
lines.push(` ${label}${pad}${displayPath} ${error('FAILED')}: ${skill.error}`);
break;
}
}
}
if (anyFailed) {
lines.push('');
lines.push('For failed editors, add the MCP server entry or project skill manually. See:');
lines.push(' https://github.com/inkeep/open-knowledge#mcp-setup');
}
if (result.legacyProjectConfigs.length > 0) {
lines.push('');
lines.push('Project MCP configs found:');
for (const proj of result.legacyProjectConfigs) {
lines.push(` ${proj.label} ${relative(cwd, proj.path)}`);
}
lines.push(
' These project-local files may override the global config. Remove them if you want fully user-scoped MCP setup in this project.',
);
}
if (result.skillInstall === 'declined') {
lines.push('');
lines.push(accent('User-global skills:'));
if (typeof result.skillsRequested === 'string') {
lines.push(
` ${dim(`none installed — --skills "${result.skillsRequested}" names no known skill bundle (known: ${USER_GLOBAL_BUNDLE_IDS.join(', ')})`)}`,
);
lines.push(` ${dim('No user-global skill was installed or removed.')}`);
} else {
lines.push(` ${dim('none installed — skipped for this run (--no-skills)')}`);
lines.push(` ${dim('No user-global skill was installed or removed; any already on this')}`);
lines.push(` ${dim('machine are untouched. Run init without the flag to install them:')}`);
lines.push(` ${dim(` ${currentCliCommandName()} init`)}`);
lines.push(
` ${dim('--no-skills covers user-global skills only, not project-local skills.')}`,
);
}
} else if (result.skillInstall) {
lines.push('');
lines.push(accent('User-global skills:'));
const bundles = result.skillBundles ?? [];
const nameWidth = Math.max(0, ...bundles.map((b) => BUNDLE_SKILL_NAME[b.bundleId].length));
for (const bundle of bundles) {
const name = BUNDLE_SKILL_NAME[bundle.bundleId].padEnd(nameWidth);
switch (bundle.result) {
case 'installed': {
const hostLabels = (result.skillHosts ?? []).map(
(id) => EDITOR_LABELS[id as EditorId] ?? id,
);
const target =
hostLabels.length > 0 ? hostLabels.join(', ') : 'the shared ~/.agents store';
lines.push(` ${name} ${success(`installed for ${target}`)}`);
break;
}
case 'skip-current':
lines.push(` ${name} ${success('already installed at current version')}`);
break;
case 'no-hosts':
lines.push(
` ${name} ${dim('skipped — no supported agent host detected in your home directory')}`,
);
break;
case 'failed':
lines.push(` ${warning(`${name} install failed`)}`);
break;
case 'opted-out':
lines.push(
` ${name} ${dim(`not installed — turned off on this machine; reinstall with ${currentCliCommandName()} init --skills ${bundle.bundleId} or Settings → Skills Studio`)}`,
);
break;
case 'decision-read-failed':
lines.push(
` ${warning(`${name} not installed — could not read whether it is turned off on this machine; rerun ${currentCliCommandName()} init once ${okUserHomeDisplayPath(SKILL_STATE_FILENAME)} is readable`)}`,
);
break;
default: {
const _exhaustive: never = bundle.result;
void _exhaustive;
}
}
}
if (result.skillInstallsCounted && bundles.some((b) => b.result === 'installed')) {
lines.push(` ${dim('Counted on skills.sh (skill name + source repo, once per machine).')}`);
lines.push(` ${dim('Opt out: DO_NOT_TRACK=1, or Settings → User → Preferences.')}`);
}
if (bundles.some((b) => b.result === 'failed')) {
lines.push(` ${warning(`Retry with: ${currentCliCommandName()} repair-skills`)}`);
}
}
if (
result.contentDirRequested !== undefined &&
result.contentDir === undefined &&
!result.contentScaffoldFailed
) {
lines.push('');
lines.push(
warning(
`⚠ --content-dir ${result.contentDirRequested} ignored — ${OK_DIR}/config.yml already exists`,
),
);
lines.push(` Edit ${OK_DIR}/config.yml → content.dir directly to change the content scope.`);
} else if (result.contentDir !== undefined && result.contentDir !== '.') {
lines.push('');
lines.push(`Content scope set to ${result.contentDir}/ (content.dir in ${OK_DIR}/config.yml).`);
} else if (
result.gitRootPromoted &&
result.contentDir === '.' &&
result.contentDirRequested === undefined
) {
lines.push('');
lines.push(warning('⚠ Content scope promoted to the git repo root'));
lines.push(
` .ok/ was initialized at ${cwd} because it contains a .git folder (one .ok/ per git repo),`,
);
lines.push(
` not the sub-folder you ran \`${currentCliCommandName()} init\` in${result.promotedFromDir ? ` (${result.promotedFromDir})` : ''}. The whole repo is now the content scope.`,
);
if (result.promotedFromDir) {
lines.push(
` To scope to just that sub-folder, re-run \`${currentCliCommandName()} init --content-dir .\` from there, or set`,
);
lines.push(` content.dir: ${result.promotedFromDir} in ${OK_DIR}/config.yml.`);
}
}
if (result.preview) {
lines.push('');
lines.push(formatPreviewBlock(result.preview, cwd));
} else if (result.previewWarning) {
lines.push('');
lines.push(`Content preview unavailable: ${result.previewWarning}`);
}
lines.push('');
lines.push(...formatSharingOutcome(result.sharing, cwd));
const seedLines = (indent: string): string[] => [
`${indent}- ${info(`${currentCliCommandName()} seed --list-packs`)} — browse the starter packs`,
`${indent}- ${info(`${currentCliCommandName()} seed`)} — scaffold an empty repo`,
];
if (anyWritten) {
const seen = new Set<EditorId>();
const configuredLabels = result.editors
.filter((e) => e.action === 'written' || e.action === 'overwritten')
.filter((e) => !seen.has(e.editorId) && seen.add(e.editorId))
.map((e) => e.label);
lines.push('');
lines.push(`${success('✓')} ${accent('Next steps:')}`);
lines.push(` 1. Open your editor (${info(configuredLabels.join(' / '))})`);
lines.push(' 2. Approve the MCP server when prompted');
let step = 3;
if (!result.contentScaffoldFailed) {
lines.push(` ${step++}. (Optional) scaffold the starter knowledge-base structure:`);
lines.push(...seedLines(' '));
}
lines.push(
` ${step}. Ask your agent to capture a source, research a topic, or build a wiki —`,
);
lines.push(' the procedures ship as skills alongside the MCP tools.');
} else if (!result.contentScaffoldFailed) {
lines.push('');
lines.push(
`${accent('Next steps:')} (optional) scaffold the starter knowledge-base structure:`,
);
lines.push(...seedLines(' '));
}
return lines.join('\n');
}
export interface InitJsonSummary {
projectRoot: string;
gitRootPromoted: boolean;
promotedFromDir: string | null;
contentDir: string;
contentDirRequested: string | null;
contentDirApplied: boolean;
contentFileCount: number | null;
previewError: string | null;
didGitInit: boolean;
mcpAction: InitCommandResult['mcpAction'];
editors: Array<{
editorId: EditorId;
label: string;
action: EditorMcpResult['action'];
configPath: string;
scope: 'project' | 'user';
}>;
}
export function buildInitJsonSummary(
result: InitCommandResult,
opts: { contentDir: string; contentFileCount: number | null },
): InitJsonSummary {
return {
projectRoot: result.projectRoot,
gitRootPromoted: result.gitRootPromoted,
promotedFromDir: result.promotedFromDir ?? null,
contentDir: opts.contentDir,
contentDirRequested: result.contentDirRequested ?? null,
contentDirApplied: result.contentDir !== undefined,
contentFileCount: opts.contentFileCount,
previewError: result.previewWarning ?? null,
didGitInit: result.didGitInit,
mcpAction: result.mcpAction,
editors: result.editors.map((e) => ({
editorId: e.editorId,
label: e.label,
action: e.action,
configPath: e.configPath,
scope: e.configScope === 'project' ? 'project' : 'user',
})),
};
}
export function detectInstalledEditors(cwd: string, home?: string): EditorId[] {
const detected: EditorId[] = [];
for (const id of ALL_EDITOR_IDS) {
if (id === 'claude-desktop') continue;
if (isEditorTargetAvailable(EDITOR_TARGETS[id], cwd, home)) {
detected.push(id);
}
}
return detected;
}
function redirectStdoutConsoleToStderr(): () => void {
const orig = { log: console.log, info: console.info, debug: console.debug };
const toErr = (...args: unknown[]): void => {
process.stderr.write(
`${args.map((a) => (typeof a === 'string' ? a : inspect(a))).join(' ')}\n`,
);
};
console.log = toErr;
console.info = toErr;
console.debug = toErr;
return () => {
console.log = orig.log;
console.info = orig.info;
console.debug = orig.debug;
};
}
export function initCommand(): Command {
return new Command('init')
.description(
`Scaffold ${OK_DIR}/ in the current directory and register the MCP server for your editor(s)`,
)
.option('--mcp', 'Register the MCP server for selected editors (default: true)', true)
.option('--no-mcp', `Scaffold the ${OK_DIR}/ directory but do not touch MCP config`)
.option(
'--dev-mcp',
'Register a local dev MCP entry (node + packages/cli/dist/cli.mjs, debug logging) in project config only, as the dev channel unless OK_CHANNEL is set',
)
.option(
'--content-dir <dir>',
`Limit content to <dir> instead of the whole project. <dir> is interpreted relative to your current directory (e.g. "." = the folder you run the command in), then saved to ${OK_DIR}/config.yml as content.dir.`,
)
.option('--json', 'Emit a structured JSON summary to stdout (diagnostics stay on stderr)')
.option(
'--skills <ids>',
'Install only the named user-global skill bundles (comma list: discovery,write-skill)',
)
.option('--no-skills', 'Do not install any user-global skill bundles')
.addOption(
new Option(
'--scope <scope>',
'Write MCP config at user level, project level, or both',
).choices(['user', 'project', 'both']),
)
.addOption(
new Option(
'--shared',
'Commit OK config alongside content (the default for fresh repos)',
).conflicts('localOnly'),
)
.addOption(
new Option(
'--local-only',
'Keep OK config out of git via .git/info/exclude (per-clone, not committed)',
).conflicts('shared'),
)
.action(
async (opts: {
mcp?: boolean;
devMcp?: boolean;
scope?: McpScope;
shared?: boolean;
localOnly?: boolean;
contentDir?: string;
json?: boolean;
skills?: string | boolean;
}) => {
const cwd = process.cwd();
if (opts.devMcp) defaultToDevChannel(process.env);
const sharing: 'shared' | 'local-only' | undefined = opts.shared
? 'shared'
: opts.localOnly
? 'local-only'
: undefined;
const restoreConsole = opts.json ? redirectStdoutConsoleToStderr() : null;
try {
let result: InitCommandResult;
try {
result = await runInit({
cwd,
mcp: opts.mcp,
devMcp: opts.devMcp,
scope: opts.scope,
sharing,
contentDir: opts.contentDir,
skills: opts.skills,
});
} catch (err) {
if (
err instanceof ContentDirError ||
err instanceof DevMcpScopeError ||
err instanceof HomeProjectRootError ||
err instanceof FilesystemRootProjectError
) {
process.stderr.write(`${err.message}\n`);
process.exitCode = 64;
return;
}
if (
err instanceof GitNotAvailableError ||
err instanceof GitProbeTimeoutError ||
err instanceof GitTooOldError
) {
process.stderr.write(`${err.message}\n`);
process.exitCode = 78;
return;
}
if (err instanceof ProjectGitInitError) {
process.stderr.write(
"open-knowledge could not initialize a git repo for this project. Re-run, or run 'git init' yourself in the project folder.\n",
);
if (err.stderr) process.stderr.write(`${err.stderr.trim()}\n`);
process.exitCode = 1;
return;
}
throw err;
}
let effectiveContentDir = result.contentDir ?? '.';
let contentFileCount: number | null = null;
const { loadConfig } = await import('../config/loader.ts');
const { resolveContentDir } = await import('@inkeep/open-knowledge-server');
let config: Awaited<ReturnType<typeof loadConfig>>['config'] | undefined;
try {
config = loadConfig(result.projectRoot).config;
effectiveContentDir = config.content.dir;
} catch (e) {
result.previewWarning = e instanceof Error ? e.message : String(e);
}
if (config) {
try {
const { previewContent } = await import('../content/preview.ts');
const contentDir = resolveContentDir(config, result.projectRoot);
result.preview = previewContent({
projectDir: result.projectRoot,
contentDir,
});
contentFileCount = result.preview.totalCount;
} catch (e) {
result.previewWarning = e instanceof Error ? e.message : String(e);
}
}
if (opts.json) {
process.stdout.write(
`${JSON.stringify(
buildInitJsonSummary(result, { contentDir: effectiveContentDir, contentFileCount }),
null,
2,
)}\n`,
);
} else {
process.stdout.write(`${formatInitResult(result, result.projectRoot)}\n`);
}
if (result.editors.some((e) => e.action === 'failed') || result.mcpAction === 'failed') {
process.exitCode = 1;
}
} finally {
restoreConsole?.();
}
},
);
}
export function formatSharingOutcome(outcome: SharingOutcome, cwd: string): string[] {
const lines: string[] = [];
switch (outcome.kind) {
case 'applied':
lines.push(accent('Sharing mode:'));
if (outcome.mode === 'local-only') {
if (outcome.action === 'added') {
lines.push(
` ${success('local-only')} — appended ${outcome.appended.length} path(s) to ${accent(`${cwd}/.git/info/exclude`)} (per-clone, not committed).`,
);
if (outcome.removed.length > 0) {
lines.push(
` cleared ${outcome.removed.length} stale entry(s) left by an older version: ${outcome.removed.join(', ')}.`,
);
}
} else if (outcome.action === 'cleaned') {
lines.push(
` ${success('local-only')} — already excluded; cleared ${outcome.removed.length} stale entry(s) left by an older version: ${outcome.removed.join(', ')}.`,
);
} else if (outcome.action === 'noop' && outcome.alreadyPresent.length > 0) {
lines.push(` ${success('local-only')} — already excluded; nothing to do.`);
} else {
lines.push(` ${success('local-only')}`);
}
} else {
if (outcome.action === 'removed') {
lines.push(
` ${success('shared')} — removed OK paths from ${accent(`${cwd}/.git/info/exclude`)}; commit the files to share with teammates.`,
);
} else {
lines.push(` ${success('shared')} — OK config will be committed alongside content.`);
}
}
return lines;
case 'refused-tracked':
lines.push(warning('Sharing mode: switch to local-only deferred'));
for (const raw of outcome.remediation.split('\n')) {
lines.push(raw.length > 0 ? ` ${raw}` : '');
}
lines.push(
` Re-run ${info(`${currentCliCommandName()} config-sharing unshare`)} after resolving to complete the switch.`,
);
return lines;
case 'no-exclude': {
if (outcome.localOnlyRequested) {
lines.push(
warning('Sharing mode: --local-only requested but no git repo found — option ignored'),
);
lines.push(
` Run ${info('git init')} (or open this folder via OK Desktop, which can scaffold a repo) and then ${info(`${currentCliCommandName()} config-sharing unshare`)}.`,
);
} else if (outcome.reason === 'no-git') {
return [];
} else {
lines.push(warning(`Sharing mode unavailable: ${outcome.reason}.`));
}
return lines;
}
}
}