Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import type { OpenKnowledgeMcpTool } from '../constants/mcp.ts';
import type { HandoffTarget } from './types.ts';
export function shellSingleQuote(s: string): string {
return `'${s.replace(/'/g, "'\\''")}'`;
}
export function fishSingleQuote(s: string): string {
return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
}
export interface TerminalLaunchCommand {
readonly executable: string;
readonly args: readonly string[];
readonly env?: Readonly<Record<string, string>>;
readonly pathPrepend?: readonly string[];
readonly supportFile?: {
readonly kind: 'claude-settings';
readonly relativePath: string;
readonly contents: string;
};
}
function claudeSettingsFileArgs(relativePath: string): readonly string[] {
return ['--settings', relativePath];
}
export function launchWithoutSupportFile(launch: TerminalLaunchCommand): TerminalLaunchCommand {
if (launch.supportFile === undefined) return launch;
const { supportFile: _supportFile, ...rest } = launch;
return { ...rest, args: [] };
}
const WINDOWS_SHELL_FAMILY_VOCABULARY = ['powershell', 'cmd', 'bash'] as const;
export type WindowsShellFamily = (typeof WINDOWS_SHELL_FAMILY_VOCABULARY)[number];
export const WINDOWS_SHELL_FAMILIES: ReadonlySet<WindowsShellFamily> = new Set(
WINDOWS_SHELL_FAMILY_VOCABULARY,
);
export function isWindowsShellFamily(value: unknown): value is WindowsShellFamily {
return typeof value === 'string' && WINDOWS_SHELL_FAMILIES.has(value as WindowsShellFamily);
}
const POWERSHELL_SINGLE_QUOTE = /['\u2018\u2019\u201A\u201B]/g;
export function psQuoteArg(value: string): string {
return `'${value.replace(POWERSHELL_SINGLE_QUOTE, '$&$&')}'`;
}
function encodeUtf8Base64(value: string): string {
const bytes = new TextEncoder().encode(value);
let binary = '';
for (const byte of bytes) binary += String.fromCharCode(byte);
return btoa(binary);
}
const TERMINAL_LAUNCH_ENV_SLOT_PREFIX = 'OK_TERMINAL_LAUNCH_ENV_';
interface TerminalLaunchEnvSlot {
readonly name: string;
readonly slot: string;
readonly value: string;
}
export function terminalLaunchEnvSlots(
env: Readonly<Record<string, string>> | undefined,
): TerminalLaunchEnvSlot[] {
return Object.entries(env ?? {}).map(([name, value], index) => ({
name,
slot: `${TERMINAL_LAUNCH_ENV_SLOT_PREFIX}${index}`,
value,
}));
}
const BASH_STRUCTURED_LAUNCH_SCRIPT =
`mapfile -d '' -t __ok_argv < <(printf '%s' "$1" | base64 -d); ` +
`((\${#__ok_argv[@]})) || exit 1; ` +
`mapfile -d '' -t __ok_env < <(printf '%s' "$2" | base64 -d); ` +
`(for ((__ok_i = 0; __ok_i < \${#__ok_env[@]}; __ok_i += 2)); do __ok_slot="\${__ok_env[__ok_i + 1]}"; ` +
`export "\${__ok_env[__ok_i]}=\${!__ok_slot}"; done; exec "\${__ok_argv[@]}"); ` +
`for ((__ok_i = 1; __ok_i < \${#__ok_env[@]}; __ok_i += 2)); do unset "\${__ok_env[__ok_i]}"; done; ` +
`exec "$BASH" --login -i`;
const TERMINAL_LAUNCH_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
export function isTerminalLaunchEnvName(name: string): boolean {
return (
TERMINAL_LAUNCH_ENV_NAME.test(name) &&
!name.toUpperCase().startsWith(TERMINAL_LAUNCH_ENV_SLOT_PREFIX)
);
}
export function encodePowerShellCommand(script: string): string {
let binary = '';
for (let i = 0; i < script.length; i += 1) {
const codeUnit = script.charCodeAt(i);
binary += String.fromCharCode(codeUnit & 0xff, codeUnit >>> 8);
}
return btoa(binary);
}
export function resolveWindowsShellFamily(shell: string): WindowsShellFamily | null {
const base = shell.split(/[\\/]/).at(-1)?.toLowerCase();
if (
base === 'pwsh' ||
base === 'pwsh.exe' ||
base === 'powershell' ||
base === 'powershell.exe'
) {
return 'powershell';
}
if (base === 'cmd' || base === 'cmd.exe') return 'cmd';
if (base === 'bash' || base === 'bash.exe') return 'bash';
return null;
}
function isCmdSafeEnvValue(value: string): boolean {
return !Array.from(value).some((ch) => ch.charCodeAt(0) < 0x20) && !/["%!&|<>^()]/u.test(value);
}
function isCmdSafeToken(value: string): boolean {
return (
value.length > 0 &&
!Array.from(value).some((ch) => ch.charCodeAt(0) < 0x20) &&
!/[\s"%!&|<>^()]/u.test(value)
);
}
const WINDOWS_SHELL_LAUNCH_FAILURE_VOCABULARY = [
'unsupported-shell',
'invalid-launch',
'unsafe-argument',
] as const;
export type WindowsShellLaunchFailureReason =
(typeof WINDOWS_SHELL_LAUNCH_FAILURE_VOCABULARY)[number];
const WINDOWS_SHELL_LAUNCH_FAILURE_REASONS: ReadonlySet<WindowsShellLaunchFailureReason> = new Set(
WINDOWS_SHELL_LAUNCH_FAILURE_VOCABULARY,
);
export function isWindowsShellLaunchFailureReason(
value: unknown,
): value is WindowsShellLaunchFailureReason {
return (
typeof value === 'string' &&
WINDOWS_SHELL_LAUNCH_FAILURE_REASONS.has(value as WindowsShellLaunchFailureReason)
);
}
export class WindowsShellLaunchError extends Error {
readonly reason: WindowsShellLaunchFailureReason;
constructor(reason: WindowsShellLaunchFailureReason) {
super(reason);
this.name = 'WindowsShellLaunchError';
this.reason = reason;
}
}
export function composeWindowsShellLaunchArgs(
shell: string,
launch: TerminalLaunchCommand,
): string[] | string {
const family = resolveWindowsShellFamily(shell);
if (family === null) throw new WindowsShellLaunchError('unsupported-shell');
if (
launch.executable.length === 0 ||
launch.executable.includes('\u0000') ||
launch.args.some((arg) => arg.includes('\u0000'))
) {
throw new WindowsShellLaunchError('invalid-launch');
}
const NUL = String.fromCharCode(0);
const envEntries = Object.entries(launch.env ?? {});
if (envEntries.some(([key, value]) => !isTerminalLaunchEnvName(key) || value.includes(NUL))) {
throw new WindowsShellLaunchError('invalid-launch');
}
const loweredNames = new Set<string>();
for (const [key] of envEntries) {
const lowered = key.toLowerCase();
if (loweredNames.has(lowered)) throw new WindowsShellLaunchError('invalid-launch');
loweredNames.add(lowered);
}
const slots = terminalLaunchEnvSlots(launch.env);
if (family === 'bash') {
const argv = [launch.executable, ...launch.args];
const pairs = slots.flatMap(({ name, slot }) => [name, slot]);
return [
'--login',
'-i',
'-c',
BASH_STRUCTURED_LAUNCH_SCRIPT,
'bash',
encodeUtf8Base64(`${argv.join(NUL)}${NUL}`),
...(pairs.length === 0 ? [] : [encodeUtf8Base64(`${pairs.join(NUL)}${NUL}`)]),
];
}
const batchTarget = /\.(?:cmd|bat)$/iu.test(launch.executable);
if (family === 'cmd' || batchTarget) {
const tokens = [launch.executable, ...launch.args];
if (tokens.some((token) => !isCmdSafeToken(token))) {
throw new WindowsShellLaunchError('unsafe-argument');
}
if (family === 'cmd') {
if (slots.some(({ value }) => !isCmdSafeEnvValue(value))) {
throw new WindowsShellLaunchError('unsafe-argument');
}
const command = tokens.join(' ');
if (slots.length === 0) return `/K ${command}`;
const assign = slots.map(({ name, slot }) => `set "${name}=!${slot}!" & `).join('');
const clear = slots.map(({ slot }) => ` & set "${slot}="`).join('');
return `/K cmd /d /v:on /c "${assign}${command}"${clear}`;
}
}
const command = `& ${psQuoteArg(launch.executable)}${launch.args
.map((arg) => ` ${psQuoteArg(arg)}`)
.join('')}`;
if (slots.length === 0) {
return ['-NoExit', '-EncodedCommand', encodePowerShellCommand(command)];
}
const names = slots.map(({ name }) => psQuoteArg(name)).join(', ');
const slotNames = slots.map(({ slot }) => psQuoteArg(slot)).join(', ');
const script =
`$__ok_names = @(${names}); $__ok_slots = @(${slotNames}); $__ok_prev = @{}; ` +
'for ($__ok_i = 0; $__ok_i -lt $__ok_names.Length; $__ok_i++) { ' +
'$__ok_prev[$__ok_names[$__ok_i]] = [Environment]::GetEnvironmentVariable($__ok_names[$__ok_i]); ' +
"[Environment]::SetEnvironmentVariable($__ok_names[$__ok_i], [Environment]::GetEnvironmentVariable($__ok_slots[$__ok_i]), 'Process') }; " +
`try { ${command} } finally { ` +
'for ($__ok_i = 0; $__ok_i -lt $__ok_names.Length; $__ok_i++) { ' +
"[Environment]::SetEnvironmentVariable($__ok_names[$__ok_i], $__ok_prev[$__ok_names[$__ok_i]], 'Process'); " +
"[Environment]::SetEnvironmentVariable($__ok_slots[$__ok_i], $null, 'Process') }; " +
'Remove-Variable __ok_names, __ok_slots, __ok_prev, __ok_i -ErrorAction SilentlyContinue }';
return ['-NoExit', '-EncodedCommand', encodePowerShellCommand(script)];
}
export function quoteWindowsShellPath(family: WindowsShellFamily, path: string): string | null {
if (path.length === 0 || /\p{Cc}/u.test(path)) return null;
if (family === 'powershell') return psQuoteArg(path);
if (family === 'bash') return shellSingleQuote(path);
if (/["%!]/u.test(path)) return null;
return `"${path}"`;
}
export type TerminalCli =
| 'claude'
| 'codex'
| 'copilot'
| 'cursor'
| 'opencode'
| 'pi'
| 'antigravity'
| 'openclaw'
| 'hermes';
export interface TerminalCliInfo {
readonly bin: string;
readonly displayName: string;
readonly docsUrl: string;
readonly handoffTarget: HandoffTarget;
readonly subcommand?: string;
readonly promptFlag?: string;
readonly startupInjection?: {
readonly submit: string;
readonly readyMarker?: string;
readonly settleMs: number;
readonly capMs: number;
};
}
export const OK_GATED_TOOL_NAMES = [
'delete',
'move',
'share_link',
'install',
'import',
] as const satisfies ReadonlyArray<OpenKnowledgeMcpTool>;
function approvedServerName(opts: BuildCliLaunchOptions): string | null {
return opts.mcpServerName ? opts.mcpServerName : null;
}
function codexAutoApproveSetting(server: string, quote: string): string {
return `mcp_servers.${server}.default_tools_approval_mode=${quote}approve${quote}`;
}
function buildClaudeSettingsJson(opts: BuildCliLaunchOptions): string | null {
const server = approvedServerName(opts);
if (server === null) return null;
const settings: {
enabledMcpjsonServers?: string[];
permissions?: { allow: string[]; ask: string[] };
} = {};
if (opts.mcpPreApprove === true) {
settings.enabledMcpjsonServers = [server];
}
if (opts.autoApproveOkTools === true) {
settings.permissions = {
allow: opts.cliCommandName
? [`mcp__${server}`, `Bash(${opts.cliCommandName} open:*)`]
: [`mcp__${server}`],
ask: OK_GATED_TOOL_NAMES.map((tool) => `mcp__${server}__${tool}`),
};
}
if (settings.enabledMcpjsonServers === undefined && settings.permissions === undefined) {
return null;
}
return JSON.stringify(settings);
}
const ESC = '\x1b';
const BRACKETED_PASTE_START = `${ESC}[200~`;
const BRACKETED_PASTE_END = `${ESC}[201~`;
const TERMINAL_LINE_BREAK_RE = /\r\n?/g;
const TERMINAL_UNSAFE_CONTROL_RE = new RegExp(
'[' + '\\u0000-\\u0008' + '\\u000b-\\u001f' + '\\u007f-\\u009f' + ']',
'g',
);
const TRAILING_LINE_BREAKS_RE = /\n*$/;
export const TERMINAL_CONTROL_LABEL_NOTICE =
'Control characters in the text above are shown as <control-NNNN> labels; the source document holds the raw characters.';
function controlLabel(control: string): string {
const codePoint = control.codePointAt(0) ?? 0;
return `<control-${codePoint.toString(16).toUpperCase().padStart(4, '0')}>`;
}
export function toTerminalPromptText(text: string): string {
let labeled = false;
const printable = text
.replace(TERMINAL_LINE_BREAK_RE, '\n')
.replace(TERMINAL_UNSAFE_CONTROL_RE, (control) => {
labeled = true;
return controlLabel(control);
});
if (!labeled) return printable;
const trailing = TRAILING_LINE_BREAKS_RE.exec(printable)?.[0] ?? '';
const body = printable.slice(0, printable.length - trailing.length);
return `${body}\n\n${TERMINAL_CONTROL_LABEL_NOTICE}${trailing}`;
}
export function buildTerminalInputBytes(text: string, bracketedPaste: boolean): string {
const printable = toTerminalPromptText(text);
return bracketedPaste ? `${BRACKETED_PASTE_START}${printable}${BRACKETED_PASTE_END}` : printable;
}
export const BRACKETED_PASTE_ENABLE_MARKER = '\x1b[?2004h';
const HERMES_INJECT_DEBOUNCE_MS = 300;
const HERMES_INJECT_CAP_MS = 4000;
const WINDOWS_INJECT_SETTLE_MS = 800;
const WINDOWS_INJECT_CAP_MS = 4000;
const WINDOWS_STARTUP_INJECTION: NonNullable<TerminalCliInfo['startupInjection']> = {
submit: '\r',
readyMarker: BRACKETED_PASTE_ENABLE_MARKER,
settleMs: WINDOWS_INJECT_SETTLE_MS,
capMs: WINDOWS_INJECT_CAP_MS,
};
export const TERMINAL_CLIS = {
claude: {
bin: 'claude',
displayName: 'Claude',
docsUrl: 'https://docs.claude.com/en/docs/claude-code',
handoffTarget: 'claude-code',
},
codex: {
bin: 'codex',
displayName: 'Codex',
docsUrl: 'https://developers.openai.com/codex/cli',
handoffTarget: 'codex',
},
copilot: {
bin: 'copilot',
displayName: 'GitHub Copilot',
docsUrl: 'https://docs.github.com/en/copilot/how-tos/copilot-cli/cli-getting-started',
handoffTarget: 'copilot',
promptFlag: '--interactive',
},
cursor: {
bin: 'cursor-agent',
displayName: 'Cursor',
docsUrl: 'https://cursor.com/docs/cli/overview',
handoffTarget: 'cursor',
},
opencode: {
bin: 'opencode',
displayName: 'OpenCode',
docsUrl: 'https://opencode.ai/docs',
handoffTarget: 'opencode',
promptFlag: '--prompt',
},
pi: {
bin: 'pi',
displayName: 'Pi',
docsUrl: 'https://pi.dev',
handoffTarget: 'pi',
},
antigravity: {
bin: 'agy',
displayName: 'Antigravity',
docsUrl: 'https://antigravity.google/docs/cli-getting-started',
handoffTarget: 'antigravity',
promptFlag: '--prompt-interactive',
},
openclaw: {
bin: 'openclaw',
subcommand: 'chat',
displayName: 'OpenClaw',
docsUrl: 'https://docs.openclaw.ai/cli/tui',
handoffTarget: 'openclaw',
promptFlag: '--message',
},
hermes: {
bin: 'hermes',
subcommand: 'chat',
displayName: 'Hermes',
docsUrl: 'https://hermes-agent.nousresearch.com/docs/user-guide/cli',
handoffTarget: 'hermes',
startupInjection: {
submit: '\r',
readyMarker: BRACKETED_PASTE_ENABLE_MARKER,
settleMs: HERMES_INJECT_DEBOUNCE_MS,
capMs: HERMES_INJECT_CAP_MS,
},
},
} as const satisfies Record<TerminalCli, TerminalCliInfo>;
export const TERMINAL_CLI_IDS = [
'claude',
'codex',
'opencode',
'cursor',
'copilot',
'pi',
'antigravity',
'openclaw',
'hermes',
] as const satisfies readonly TerminalCli[];
export interface BuildCliLaunchOptions {
readonly mcpPreApprove?: boolean;
readonly autoApproveOkTools?: boolean;
readonly mcpServerName?: string;
readonly cliCommandName?: string;
}
export function buildWindowsCliLaunch(
cli: TerminalCli,
_prompt: string | null | undefined,
opts: BuildCliLaunchOptions = {},
): TerminalLaunchCommand {
const info: TerminalCliInfo = TERMINAL_CLIS[cli];
if (cli === 'claude') {
const settingsJson = buildClaudeSettingsJson(opts);
if (settingsJson !== null) {
const variant = [
opts.mcpPreApprove === true ? 'mcp' : null,
opts.autoApproveOkTools === true ? 'tools' : null,
]
.filter((part): part is string => part !== null)
.join('-');
const relativePath = `.ok/local/terminal/claude-settings-${variant}.json`;
return {
executable: info.bin,
args: [...claudeSettingsFileArgs(relativePath)],
supportFile: {
kind: 'claude-settings',
relativePath,
contents: settingsJson,
},
};
}
}
const server = approvedServerName(opts);
if (cli === 'codex' && opts.autoApproveOkTools === true && server !== null) {
return {
executable: info.bin,
args: ['-c', codexAutoApproveSetting(server, '')],
};
}
return {
executable: info.bin,
args: info.subcommand ? [info.subcommand] : [],
};
}
export function buildPosixCliLaunch(
cli: TerminalCli,
prompt: string | null | undefined,
opts: BuildCliLaunchOptions = {},
): TerminalLaunchCommand {
const info: TerminalCliInfo = TERMINAL_CLIS[cli];
const server = approvedServerName(opts);
const settingsJson = cli === 'claude' ? buildClaudeSettingsJson(opts) : null;
const fixedArgs =
settingsJson !== null
? ['--settings', settingsJson]
: cli === 'codex' && opts.autoApproveOkTools === true && server !== null
? ['-c', codexAutoApproveSetting(server, '"')]
: [];
const args = [...(info.subcommand ? [info.subcommand] : []), ...fixedArgs];
if (info.startupInjection != null || prompt == null || prompt.length === 0) {
return { executable: info.bin, args };
}
return {
executable: info.bin,
args: [...args, ...(info.promptFlag ? [info.promptFlag] : []), toTerminalPromptText(prompt)],
};
}
export function startupInjectionFor(
cli: TerminalCli,
platform: NodeJS.Platform,
): TerminalCliInfo['startupInjection'] {
const info: TerminalCliInfo = TERMINAL_CLIS[cli];
return info.startupInjection ?? (platform === 'win32' ? WINDOWS_STARTUP_INJECTION : undefined);
}
export function buildStartupInjectionBytes(
cli: TerminalCli,
prompt: string | null | undefined,
platform: NodeJS.Platform,
): string | null {
const injection = startupInjectionFor(cli, platform);
if (injection == null || prompt == null || prompt.length === 0) return null;
return `${buildTerminalInputBytes(prompt, true)}${injection.submit}`;
}