Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat: agent ability to focus a page in the editor (PRD-7183) (#2269)

tim-inkeep8996d69eaf1d
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 45bb0a102..ec48e1e12 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -9,7 +9,6 @@ if (process.argv.includes('--no-color')) {
}
import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
import { resolve } from 'node:path';
import type { Config } from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
@@ -35,7 +34,7 @@ import { shareCommand } from './commands/share/index.ts';
import { sharingCommand } from './commands/sharing/index.ts';
import {
decideSingleFileTarget,
- hasMarkdownExtension,
+ isFileishTarget,
scanRootArgv,
} from './commands/single-file-dispatch.ts';
import { createRealSingleFileOpenDeps, runSingleFileOpen } from './commands/single-file-open.ts';
@@ -186,7 +185,7 @@ Examples:
const knownSubcommands = new Set(program.commands.map((c) => c.name()));
const target = decideSingleFileTarget(scanned.operands, {
knownSubcommands,
- isFileish: (t) => hasMarkdownExtension(t) || existsSync(resolve(baseDir, t)),
+ isFileish: (t) => isFileishTarget(resolve(baseDir, t), t),
});
if (target !== null) {
const code = await runSingleFileOpen(
diff --git a/packages/cli/src/commands/open.test.ts b/packages/cli/src/commands/open.test.ts
index 4c7991fdf..1600f9be7 100644
--- a/packages/cli/src/commands/open.test.ts
+++ b/packages/cli/src/commands/open.test.ts
@@ -13,6 +13,7 @@ function makeDeps(overrides: Partial<OpenDeps> = {}): {
const deps: OpenDeps = {
detectBundlePath: () => null,
resolveBaseUrl: () => null,
+ classifyName: () => 'doc',
openTarget: (t) => opened.push(t),
log: (m) => logs.push(m),
error: (m) => errors.push(m),
@@ -49,26 +50,95 @@ describe('runOpen', () => {
expect(errors).toHaveLength(1);
});
- test('folder takes the browser route even when a desktop bundle is present', () => {
+ test('folder with a desktop bundle → folder= deep link, exit 0', () => {
const { deps, opened } = makeDeps({
detectBundlePath: () => '/Applications/OpenKnowledge.app',
+ });
+ const code = runOpen('specs/foo/', { project: '/p' }, deps);
+ expect(code).toBe(0);
+ expect(opened).toEqual(['openknowledge://open?project=%2Fp&folder=specs%2Ffoo']);
+ });
+
+ test('folder, no bundle but UI running → browser folder route, exit 0', () => {
+ const { deps, opened } = makeDeps({
+ detectBundlePath: () => null,
resolveBaseUrl: () => 'http://localhost:5173',
});
- const code = runOpen('specs/foo', { folder: true, project: '/p' }, deps);
+ const code = runOpen('specs/foo/', { project: '/p' }, deps);
expect(code).toBe(0);
expect(opened).toEqual(['http://localhost:5173/#/specs/foo/']);
});
- test('trailing slash infers folder intent without --folder', () => {
- const { deps, opened } = makeDeps({ resolveBaseUrl: () => 'http://localhost:5173' });
+ test('auto-detects a folder from disk (no trailing slash needed)', () => {
+ const { deps, opened } = makeDeps({
+ detectBundlePath: () => '/Applications/OpenKnowledge.app',
+ classifyName: () => 'folder',
+ });
+ const code = runOpen('specs/foo', { project: '/p' }, deps);
+ expect(code).toBe(0);
+ expect(opened).toEqual(['openknowledge://open?project=%2Fp&folder=specs%2Ffoo']);
+ });
+
+ test('trailing slash infers folder intent even when disk classify says doc', () => {
+ const { deps, opened } = makeDeps({
+ resolveBaseUrl: () => 'http://localhost:5173',
+ classifyName: () => 'doc',
+ });
const code = runOpen('specs/foo/', {}, deps);
expect(code).toBe(0);
expect(opened).toEqual(['http://localhost:5173/#/specs/foo/']);
});
+ test('skill with a desktop bundle → rides doc=__skill__/<scope>/<name> deep link', () => {
+ const { deps, opened } = makeDeps({
+ detectBundlePath: () => '/Applications/OpenKnowledge.app',
+ });
+ const code = runOpen('trip-log', { skill: true, project: '/p' }, deps);
+ expect(code).toBe(0);
+ expect(opened).toEqual([
+ 'openknowledge://open?project=%2Fp&doc=__skill__%2Fproject%2Ftrip-log',
+ ]);
+ });
+
+ test('skill --scope global, no bundle but UI running → browser skill route', () => {
+ const { deps, opened } = makeDeps({ resolveBaseUrl: () => 'http://localhost:5173' });
+ const code = runOpen('trip-log', { skill: true, scope: 'global', project: '/p' }, deps);
+ expect(code).toBe(0);
+ expect(opened).toEqual(['http://localhost:5173/#/__skill__/global/trip-log']);
+ });
+
+ test('skill with an invalid --scope → error, exit 1', () => {
+ const { deps, errors } = makeDeps({
+ detectBundlePath: () => '/Applications/OpenKnowledge.app',
+ });
+ const code = runOpen('trip-log', { skill: true, scope: 'nonsense', project: '/p' }, deps);
+ expect(code).toBe(1);
+ expect(errors).toHaveLength(1);
+ });
+
+ test('skill, neither desktop nor UI → error, exit 1, nothing opened', () => {
+ const { deps, opened, errors } = makeDeps();
+ const code = runOpen('trip-log', { skill: true, project: '/p' }, deps);
+ expect(code).toBe(1);
+ expect(opened).toEqual([]);
+ expect(errors).toHaveLength(1);
+ });
+
+ test('skill name with a traversal/unsafe segment → error before any open', () => {
+ const { deps, opened, errors } = makeDeps({
+ detectBundlePath: () => '/Applications/OpenKnowledge.app',
+ });
+ for (const bad of ['../../etc', '/abs', 'a\\b']) {
+ const code = runOpen(bad, { skill: true, project: '/p' }, deps);
+ expect(code).toBe(1);
+ }
+ expect(opened).toEqual([]);
+ expect(errors.length).toBeGreaterThanOrEqual(3);
+ });
+
test('folder with no UI running → error, exit 1', () => {
const { deps, errors } = makeDeps({ resolveBaseUrl: () => null });
- const code = runOpen('specs/foo', { folder: true, project: '/p' }, deps);
+ const code = runOpen('specs/foo/', { project: '/p' }, deps);
expect(code).toBe(1);
expect(errors).toHaveLength(1);
});
@@ -97,7 +167,7 @@ describe('runOpen', () => {
test('rejects unsafe folder names too', () => {
const { deps, opened, errors } = makeDeps({ resolveBaseUrl: () => 'http://localhost:5173' });
- const code = runOpen('specs/..', { folder: true, project: '/p' }, deps);
+ const code = runOpen('specs/..', { project: '/p' }, deps);
expect(code).toBe(1);
expect(opened).toEqual([]);
expect(errors).toHaveLength(1);
diff --git a/packages/cli/src/commands/open.ts b/packages/cli/src/commands/open.ts
index b1945382a..0eb656552 100644
--- a/packages/cli/src/commands/open.ts
+++ b/packages/cli/src/commands/open.ts
@@ -1,8 +1,11 @@
import { spawn as nodeSpawn } from 'node:child_process';
-import { resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { MANAGED_ARTIFACT_SCOPES, type SkillScope } from '@inkeep/open-knowledge-core';
import {
encodeDocName,
encodeFolderRoute,
+ encodeSkillRoute,
resolveLockDir,
resolveUiInfo,
} from '@inkeep/open-knowledge-server';
@@ -10,13 +13,15 @@ import { Command } from 'commander';
import { createRealDetectDeps, type DetectResult, detectDesktop } from './desktop-dispatch.ts';
export interface OpenOptions {
- folder?: boolean;
+ skill?: boolean;
+ scope?: string;
project?: string;
}
export interface OpenDeps {
detectBundlePath: () => string | null;
resolveBaseUrl: (projectDir: string) => string | null;
+ classifyName: (projectDir: string, name: string) => 'doc' | 'folder';
openTarget: (target: string) => void;
log: (message: string) => void;
error: (message: string) => void;
@@ -34,6 +39,20 @@ export function createRealOpenDeps(
return {
detectBundlePath: () => detect().bundlePath ?? null,
resolveBaseUrl: (projectDir) => resolveUiInfo({ lockDir: resolveLockDir(projectDir) }).baseUrl,
+ classifyName: (projectDir, name) => {
+ const abs = join(projectDir, name);
+ try {
+ return statSync(abs).isDirectory() ? 'folder' : 'doc';
+ } catch (err) {
+ const code = (err as { code?: string } | null)?.code;
+ if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+ process.stderr.write(
+ `[ok open] statSync failed for ${abs} (${code ?? 'unknown'}); treating as a doc\n`,
+ );
+ }
+ return 'doc';
+ }
+ },
openTarget: (target) => {
const child = nodeSpawn('open', [target], {
detached: true,
@@ -47,51 +66,96 @@ export function createRealOpenDeps(
};
}
+function isUnsafeName(name: string): boolean {
+ return name.startsWith('/') || name.includes('\\') || name.split('/').includes('..');
+}
+
+function noTargetError(deps: OpenDeps): number {
+ deps.error(
+ 'No OpenKnowledge desktop app found and no UI is running. ' +
+ 'Install OK Desktop, or start a UI with `ok ui`, then retry.',
+ );
+ return 1;
+}
+
+function openDesktopDeepLink(
+ projectDir: string,
+ param: 'doc' | 'folder',
+ target: string,
+ deps: OpenDeps,
+): void {
+ const deepLink = `openknowledge://open?project=${encodeURIComponent(
+ projectDir,
+ )}&${param}=${encodeURIComponent(target)}`;
+ deps.openTarget(deepLink);
+}
+
export function runOpen(name: string, options: OpenOptions, deps: OpenDeps): number {
const projectDir = resolve(options.project ?? process.cwd());
- const isFolder = options.folder === true || /\/+$/.test(name);
const cleanName = name.replace(/\/+$/, '');
if (!cleanName) {
- deps.error('Nothing to open: pass a doc path (e.g. `ok open specs/foo/SPEC`).');
+ deps.error(
+ 'Nothing to open: pass a doc, folder, or skill name (e.g. `ok open specs/foo/SPEC`).',
+ );
return 1;
}
- if (
- cleanName.startsWith('/') ||
- cleanName.includes('\\') ||
- cleanName.split('/').includes('..')
- ) {
+ if (isUnsafeName(cleanName)) {
deps.error(
`Invalid name "${cleanName}": must be a relative path with no '..' segments, leading '/', or backslashes.`,
);
return 1;
}
- if (isFolder) {
- const baseUrl = deps.resolveBaseUrl(projectDir);
- if (!baseUrl) {
+ if (options.skill === true) {
+ const scope = (options.scope ?? 'project') as SkillScope;
+ if (!(MANAGED_ARTIFACT_SCOPES as readonly string[]).includes(scope)) {
deps.error(
- `No OpenKnowledge UI is running for ${projectDir}. Folder preview requires a running UI — start one with \`ok ui\`, then retry.`,
+ `Invalid --scope "${options.scope}": expected one of ${MANAGED_ARTIFACT_SCOPES.join(', ')}.`,
);
return 1;
}
- const url = `${baseUrl}/#/${encodeFolderRoute(cleanName)}`;
- deps.openTarget(url);
- deps.log(`Opening folder ${cleanName} in your browser: ${url}`);
- return 0;
+ const bundlePath = deps.detectBundlePath();
+ if (bundlePath) {
+ openDesktopDeepLink(projectDir, 'doc', `__skill__/${scope}/${cleanName}`, deps);
+ deps.log(`Opening skill ${cleanName} (${scope}) in the OpenKnowledge desktop app.`);
+ return 0;
+ }
+ const baseUrl = deps.resolveBaseUrl(projectDir);
+ if (baseUrl) {
+ const url = `${baseUrl}/#/${encodeSkillRoute(scope, cleanName)}`;
+ deps.openTarget(url);
+ deps.log(`Opening skill ${cleanName} (${scope}) in your browser: ${url}`);
+ return 0;
+ }
+ return noTargetError(deps);
}
+ const isFolder = /\/+$/.test(name) || deps.classifyName(projectDir, cleanName) === 'folder';
+
const bundlePath = deps.detectBundlePath();
+ if (isFolder) {
+ if (bundlePath) {
+ openDesktopDeepLink(projectDir, 'folder', cleanName, deps);
+ deps.log(`Opening folder ${cleanName} in the OpenKnowledge desktop app.`);
+ return 0;
+ }
+ const baseUrl = deps.resolveBaseUrl(projectDir);
+ if (baseUrl) {
+ const url = `${baseUrl}/#/${encodeFolderRoute(cleanName)}`;
+ deps.openTarget(url);
+ deps.log(`Opening folder ${cleanName} in your browser: ${url}`);
+ return 0;
+ }
+ return noTargetError(deps);
+ }
+
if (bundlePath) {
- const deepLink = `openknowledge://open?project=${encodeURIComponent(
- projectDir,
- )}&doc=${encodeURIComponent(cleanName)}`;
- deps.openTarget(deepLink);
+ openDesktopDeepLink(projectDir, 'doc', cleanName, deps);
deps.log(`Opening ${cleanName} in the OpenKnowledge desktop app.`);
return 0;
}
-
const baseUrl = deps.resolveBaseUrl(projectDir);
if (baseUrl) {
const url = `${baseUrl}/#/${encodeDocName(cleanName)}`;
@@ -99,22 +163,25 @@ export function runOpen(name: string, options: OpenOptions, deps: OpenDeps): num
deps.log(`Opening ${cleanName} in your browser: ${url}`);
return 0;
}
-
- deps.error(
- 'No OpenKnowledge desktop app found and no UI is running. ' +
- 'Install OK Desktop, or start a UI with `ok ui`, then retry.',
- );
- return 1;
+ return noTargetError(deps);
}
export function openCommand(): Command {
return new Command('open')
- .description('Open a doc in the OK Desktop app (folders open in the browser)')
+ .description(
+ 'Open a doc, folder, or skill in the OK Desktop app (falls back to the browser UI). ' +
+ 'Docs and folders are auto-detected — no flag needed.',
+ )
.argument(
- '<doc>',
- 'Extension-less doc path (e.g. specs/foo/SPEC), or a folder path with --folder',
+ '<name>',
+ 'Doc path (specs/foo/SPEC), folder path (specs/foo or specs/foo/), or a skill name with --skill',
+ )
+ .option('--skill', 'Open <name> as a skill in the skill editor')
+ .option(
+ '--scope <scope>',
+ `Skill scope when --skill is set: ${MANAGED_ARTIFACT_SCOPES.join(' | ')}`,
+ 'project',
)
- .option('--folder', 'Treat <doc> as a folder and open the folder route in the browser')
.option('--project <dir>', 'Project root (defaults to the current directory)')
.action((name: string, options: OpenOptions) => {
process.exitCode = runOpen(name, options, createRealOpenDeps());
diff --git a/packages/cli/src/commands/single-file-dispatch.test.ts b/packages/cli/src/commands/single-file-dispatch.test.ts
index 45e3e05a4..b8995be91 100644
--- a/packages/cli/src/commands/single-file-dispatch.test.ts
+++ b/packages/cli/src/commands/single-file-dispatch.test.ts
@@ -1,7 +1,11 @@
-import { describe, expect, test } from 'bun:test';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
import {
decideSingleFileTarget,
hasMarkdownExtension,
+ isFileishTarget,
scanRootArgv,
} from './single-file-dispatch.ts';
@@ -93,3 +97,31 @@ describe('hasMarkdownExtension', () => {
expect(hasMarkdownExtension('a.md.txt')).toBe(false);
});
});
+
+describe('isFileishTarget (fs-backed predicate)', () => {
+ let dir: string;
+ beforeAll(() => {
+ dir = mkdtempSync(join(tmpdir(), 'ok-fileish-'));
+ writeFileSync(join(dir, 'note.md'), '# note');
+ writeFileSync(join(dir, 'data.json'), '{}');
+ mkdirSync(join(dir, 'a-folder'));
+ });
+ afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+ test('a markdown-extension token is fileish (even if it does not exist)', () => {
+ expect(isFileishTarget(join(dir, 'missing.md'), 'missing.md')).toBe(true);
+ });
+
+ test('an existing regular file is fileish', () => {
+ expect(isFileishTarget(join(dir, 'data.json'), 'data.json')).toBe(true);
+ expect(isFileishTarget(join(dir, 'note.md'), 'note.md')).toBe(true);
+ });
+
+ test('an existing DIRECTORY is NOT fileish — so `ok open <folder>` falls through to the open command', () => {
+ expect(isFileishTarget(join(dir, 'a-folder'), 'a-folder')).toBe(false);
+ });
+
+ test('a non-existent non-markdown token is not fileish', () => {
+ expect(isFileishTarget(join(dir, 'nope'), 'nope')).toBe(false);
+ });
+});
diff --git a/packages/cli/src/commands/single-file-dispatch.ts b/packages/cli/src/commands/single-file-dispatch.ts
index 084db8771..16bbf8f2e 100644
--- a/packages/cli/src/commands/single-file-dispatch.ts
+++ b/packages/cli/src/commands/single-file-dispatch.ts
@@ -1,3 +1,5 @@
+import { statSync } from 'node:fs';
+
const VALUE_TAKING_GLOBAL_FLAGS = new Set(['--cwd', '--log-level']);
export interface ScannedRootArgv {
@@ -61,7 +63,22 @@ export function decideSingleFileTarget(
}
/** Markdown-extension test mirroring `SUPPORTED_DOC_EXTENSIONS` — the cheap half
- * of the fileish predicate (the other half is an existing-file `existsSync`). */
+ * of the fileish predicate (the other half is an existing-regular-file stat). */
export function hasMarkdownExtension(token: string): boolean {
return /\.(md|mdx)$/i.test(token);
}
+
+export function isFileishTarget(absPath: string, token: string): boolean {
+ if (hasMarkdownExtension(token)) return true;
+ try {
+ return statSync(absPath).isFile();
+ } catch (err) {
+ const code = (err as { code?: string } | null)?.code;
+ if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+ process.stderr.write(
+ `[ok] statSync failed for ${absPath} (${code ?? 'unknown'}); treating as non-fileish\n`,
+ );
+ }
+ return false;
+ }
+}
diff --git a/packages/cli/src/mcp/server.ts b/packages/cli/src/mcp/server.ts
index 52fdde026..706849c55 100644
--- a/packages/cli/src/mcp/server.ts
+++ b/packages/cli/src/mcp/server.ts
@@ -258,6 +258,7 @@ export async function startGlobalMcpServer(
resolveCwd,
config: resolveConfigForCwd,
identityRef,
+ isDesktopTerminal: process.env.OK_DESKTOP_TERMINAL === '1',
});
const transport = new StdioServerTransport();
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index ee53a24ba..db2ad3b67 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -554,6 +554,9 @@ function ensureWindowManager() {
);
return win as unknown as BrowserWindowLike;
},
+ activateApp: () => {
+ if (process.platform === 'darwin') app.focus({ steal: true });
+ },
forkUtility: (entry, args, opts) => {
const child = utilityProcess.fork(entry, args, {
...opts,
diff --git a/packages/desktop/src/main/url-scheme.test.ts b/packages/desktop/src/main/url-scheme.test.ts
index 32b6d4566..a3accbbb5 100644
--- a/packages/desktop/src/main/url-scheme.test.ts
+++ b/packages/desktop/src/main/url-scheme.test.ts
@@ -8,6 +8,7 @@ describe('parseOpenKnowledgeUrl — valid inputs', () => {
expect(result).toEqual({
host: 'open',
project: '/abs/path',
+ kind: 'doc',
doc: 'foo.md',
});
});
@@ -19,10 +20,33 @@ describe('parseOpenKnowledgeUrl — valid inputs', () => {
expect(result).toEqual({
host: 'open',
project: '/abs/my path',
+ kind: 'doc',
doc: 'foo bar.md',
});
});
+ test('parses a folder= deep link with kind folder', () => {
+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&folder=specs%2Ffoo')).toEqual({
+ host: 'open',
+ project: '/abs',
+ kind: 'folder',
+ doc: 'specs/foo',
+ });
+ });
+
+ test('rejects when BOTH doc and folder are present (ambiguous)', () => {
+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&doc=a&folder=b')).toBeNull();
+ });
+
+ test('rejects when NEITHER doc nor folder is present', () => {
+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs')).toBeNull();
+ });
+
+ test('applies the same traversal defense to folder= as doc=', () => {
+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&folder=a%2F..%2Fb')).toBeNull();
+ expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&folder=%2Fabs')).toBeNull();
+ });
+
test('accepts flat doc-name', () => {
expect(parseOpenKnowledgeUrl('openknowledge://open?project=/abs&doc=a_b-c.md')).toMatchObject({
doc: 'a_b-c.md',
diff --git a/packages/desktop/src/main/url-scheme.ts b/packages/desktop/src/main/url-scheme.ts
index 8a2c842ba..178ae3974 100644
--- a/packages/desktop/src/main/url-scheme.ts
+++ b/packages/desktop/src/main/url-scheme.ts
@@ -20,6 +20,7 @@ function shareTargetPath(target: ShareTarget): string {
interface ParsedOpenKnowledgeUrl {
readonly host: 'open';
readonly project: string;
+ readonly kind: 'doc' | 'folder';
readonly doc: string;
}
@@ -177,13 +178,17 @@ export function parseOpenKnowledgeUrl(input: string): ParsedOpenKnowledgeUrl | n
const rawProject = parsed.searchParams.get('project');
const rawDoc = parsed.searchParams.get('doc');
- if (!rawProject || !rawDoc) return null;
+ const rawFolder = parsed.searchParams.get('folder');
+ if (!rawProject) return null;
+ if ((rawDoc == null) === (rawFolder == null)) return null;
+ const kind: 'doc' | 'folder' = rawDoc != null ? 'doc' : 'folder';
+ const rawTarget = (rawDoc ?? rawFolder) as string;
let project: string;
let doc: string;
try {
project = decodeURIComponent(rawProject);
- doc = decodeURIComponent(rawDoc);
+ doc = decodeURIComponent(rawTarget);
} catch {
return null;
}
@@ -202,6 +207,7 @@ export function parseOpenKnowledgeUrl(input: string): ParsedOpenKnowledgeUrl | n
return {
host: 'open',
project: resolve(project),
+ kind,
doc,
};
}
@@ -649,11 +655,13 @@ export function registerProtocolHandler(deps: ProtocolHandlerDeps): ProtocolHand
}
const existing = deps.focusWindowForProject(parsed.project);
if (existing) {
- deps.sendDeepLink(existing, { doc: parsed.doc, kind: 'doc' });
+ deps.sendDeepLink(existing, { doc: parsed.doc, kind: parsed.kind });
return;
}
void deps
- .openProject(parsed.project, { pendingDeepLinkTarget: { kind: 'doc', path: parsed.doc } })
+ .openProject(parsed.project, {
+ pendingDeepLinkTarget: { kind: parsed.kind, path: parsed.doc },
+ })
.catch((err) => {
deps.log?.warn(
{ err: (err as Error).message, project: parsed.project },
diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.ts
index b735ea1ca..994e6166a 100644
--- a/packages/desktop/src/main/window-manager.ts
+++ b/packages/desktop/src/main/window-manager.ts
@@ -41,6 +41,8 @@ export interface BrowserWindowLike {
isMinimized?(): boolean;
isDestroyed?(): boolean;
isVisible?(): boolean;
+ moveTop?(): void;
+ isFocused?(): boolean;
close?(): void;
destroy?(): void;
on(event: 'closed', cb: () => void): void;
@@ -145,6 +147,7 @@ export interface WindowManagerDeps {
showGate: ShowGateRegistry;
runClean?(opts: { lockDir: string }): Promise<void>;
realpathSync?(p: string): string;
+ activateApp?(): void;
readServerLock?(lockDir: string): ServerLockMetadataLike | null;
isProcessAlive?(pid: number): boolean;
hostname?(): string;
@@ -232,11 +235,17 @@ export class WindowManager {
focusWindowForProject(projectPath: string): BrowserWindowLike | null {
const ctx = this.windowsByPath.get(this.canonicalizeKey(projectPath));
if (!ctx) return null;
- const win = ctx.window;
+ this.bringToFront(ctx.window);
+ return ctx.window;
+ }
+
+ private bringToFront(win: BrowserWindowLike): void {
if (win.isMinimized?.()) win.restore?.();
win.show?.();
+ const alreadyFrontmost = win.isFocused?.() === true;
+ win.moveTop?.();
win.focus();
- return win;
+ if (!alreadyFrontmost) this.deps.activateApp?.();
}
getContextForBrowserWindow(win: BrowserWindowLike): ProjectContext | undefined {
@@ -463,7 +472,7 @@ export class WindowManager {
const existing = this.windowsByPath.get(canonicalKey);
if (existing) {
if (existing.window.isDestroyed?.() !== true) {
- existing.window.focus();
+ this.bringToFront(existing.window);
return existing;
}
this.deps.log?.warn(
@@ -786,7 +795,7 @@ export class WindowManager {
const existing = this.windowsByPath.get(canonicalKey);
if (existing) {
if (existing.window.isDestroyed?.() !== true) {
- existing.window.focus();
+ this.bringToFront(existing.window);
return existing;
}
this.deps.log?.warn(
@@ -800,7 +809,7 @@ export class WindowManager {
if (inFlight) {
const ctx = await inFlight;
if (ctx.window.isDestroyed?.() !== true) {
- ctx.window.focus();
+ this.bringToFront(ctx.window);
return ctx;
}
return this.createEphemeralWindow(opts);
diff --git a/packages/desktop/src/utility/pty-host.ts b/packages/desktop/src/utility/pty-host.ts
index 4a9d5303c..6b38bacd3 100644
--- a/packages/desktop/src/utility/pty-host.ts
+++ b/packages/desktop/src/utility/pty-host.ts
@@ -142,6 +142,7 @@ export function buildShellEnv(
if (stripped.has(key)) continue;
out[key] = value;
}
+ out.OK_DESKTOP_TERMINAL = '1';
return out;
}
diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.ts
index 4a0beb913..c05dca32a 100644
--- a/packages/desktop/tests/main/window-manager.test.ts
+++ b/packages/desktop/tests/main/window-manager.test.ts
@@ -32,7 +32,7 @@ function makeUtility(pid: number): MockUtility {
};
}
-function makeWindow(opts?: { minimized?: boolean }): BrowserWindowLike & {
+function makeWindow(opts?: { minimized?: boolean; focused?: boolean }): BrowserWindowLike & {
fireClose: () => void;
fireDomReady: () => void;
fireDidFinishLoad: () => void;
@@ -56,6 +56,8 @@ function makeWindow(opts?: { minimized?: boolean }): BrowserWindowLike & {
minimized = false;
}),
isMinimized: mock(() => minimized),
+ moveTop: mock(() => {}),
+ isFocused: mock(() => opts?.focused ?? false),
isDestroyed: mock(() => destroyed),
isVisible: mock(() => visible),
on: mock((_event: 'closed', cb: () => void) => {
@@ -101,6 +103,7 @@ interface TestEnv {
forkUtilityArgs: string[][];
timers: Array<{ cb: () => void; ms: number }>;
killProbe: ReturnType<typeof mock>;
+ activateApp: ReturnType<typeof mock>;
showGateRegistrations: ShowGateRegistration[];
deps: WindowManagerDeps;
}
@@ -112,6 +115,7 @@ function buildEnv(): TestEnv {
const forkUtilityArgs: string[][] = [];
const timers: Array<{ cb: () => void; ms: number }> = [];
const killProbe = mock(() => {});
+ const activateApp = mock(() => {});
const showGateRegistrations: ShowGateRegistration[] = [];
const showGate: ShowGateRegistry = {
register: (window, opts) => {
@@ -135,6 +139,7 @@ function buildEnv(): TestEnv {
forkUtilityArgs,
timers,
killProbe,
+ activateApp,
showGateRegistrations,
deps: {
createWindow: (opts) => {
@@ -157,6 +162,7 @@ function buildEnv(): TestEnv {
return null;
},
killProbe,
+ activateApp,
showGate,
},
};
@@ -1417,6 +1423,36 @@ describe('WindowManager.focusWindowForProject (M4 URL-scheme warm-start)', () =>
expect(w.focus).toHaveBeenCalled();
});
+ test('brings a backgrounded window to the front: show + moveTop + focus + app steal', async () => {
+ const wm = new WindowManager(env.deps);
+ const p = wm.createProjectWindow({ projectPath: '/tmp/bg-proj' });
+ env.utilities[0]?.fire({ type: 'ready', port: 51210, apiOrigin: 'http://localhost:51210' });
+ const ctx = await p;
+
+ wm.focusWindowForProject('/tmp/bg-proj');
+ expect(ctx.window.show).toHaveBeenCalled();
+ expect(ctx.window.moveTop).toHaveBeenCalled();
+ expect(ctx.window.focus).toHaveBeenCalled();
+ expect(env.activateApp).toHaveBeenCalled();
+ });
+
+ test('skips the app-level focus steal when the window is already frontmost', async () => {
+ const w = makeWindow({ focused: true });
+ env.deps.createWindow = () => {
+ env.createWindowOpts.push({ additionalArguments: [], title: '' });
+ env.windows.push(w);
+ return w;
+ };
+ const wm = new WindowManager(env.deps);
+ const p = wm.createProjectWindow({ projectPath: '/tmp/frontmost-proj' });
+ env.utilities[0]?.fire({ type: 'ready', port: 51211, apiOrigin: 'http://localhost:51211' });
+ await p;
+
+ wm.focusWindowForProject('/tmp/frontmost-proj');
+ expect(w.focus).toHaveBeenCalled();
+ expect(env.activateApp).not.toHaveBeenCalled();
+ });
+
test('canonicalizes project path before lookup (resolve equivalence)', async () => {
const wm = new WindowManager(env.deps);
const p = wm.createProjectWindow({ projectPath: '/tmp/canon' });
diff --git a/packages/desktop/tests/utility/pty-host.test.ts b/packages/desktop/tests/utility/pty-host.test.ts
index 7fbcad66e..35919bb0b 100644
--- a/packages/desktop/tests/utility/pty-host.test.ts
+++ b/packages/desktop/tests/utility/pty-host.test.ts
@@ -161,6 +161,13 @@ describe('setupPtyHost — create', () => {
expect(env.OK_LOCK_KIND).toBeUndefined();
expect(env.PATH).toBe('/usr/bin');
});
+
+ test('marks the shell as the OK Desktop terminal (OK_DESKTOP_TERMINAL=1)', () => {
+ const h = makeHarness({ env: { SHELL: '/bin/zsh', OK_DESKTOP_TERMINAL: '' } });
+ h.fire(CREATE());
+ const env = h.spawnCalls[0]?.options.env ?? {};
+ expect(env.OK_DESKTOP_TERMINAL).toBe('1');
+ });
});
describe('setupPtyHost — streaming', () => {
@@ -498,7 +505,7 @@ describe('setupPtyHost — incoming message validation (asIncomingMessage guard)
});
describe('buildShellEnv', () => {
- test('strips markers, drops undefined, preserves the rest', () => {
+ test('strips markers, drops undefined, preserves the rest, marks the desktop terminal', () => {
const env = buildShellEnv({
PATH: '/usr/bin',
HOME: '/Users/x',
@@ -506,7 +513,7 @@ describe('buildShellEnv', () => {
OK_LOCK_KIND: 'interactive',
MAYBE: undefined,
});
- expect(env).toEqual({ PATH: '/usr/bin', HOME: '/Users/x' });
+ expect(env).toEqual({ PATH: '/usr/bin', HOME: '/Users/x', OK_DESKTOP_TERMINAL: '1' });
});
});
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index d0655c1a5..c06ada956 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/assets/skills/project/SKILL.md
@@ -19,7 +19,7 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th
1. **Reads:** `exec("cat …")` for one doc, `exec("ls -A …")` for a directory (folder defaults + template menu), `exec("grep …")` for literal, `search` for ranked retrieval. Native `Read` / `Grep` only on source code (`.ts` / `.py` / …), never on in-scope `.md` / `.mdx`.
2. **Writes:** `write({ document: { path, content } })` for a new or full-replace doc; `edit({ document: { path, find, replace } })` for a body find/replace; `edit({ document: { path, frontmatter } })` for a frontmatter merge-patch (`null` deletes a key). `delete({ document })` removes, `move({ from, to })` moves/renames. Body find/replace is body-only. Pass a one-line `summary` (≤80 chars, user-facing outcome) on every content write.
-3. **Preview:** every read/write response carries a route-only `previewUrl` (`/#/<doc>`, no host:port). Open the browser once at session start. Don't `preview_screenshot` to confirm edits — the tool response is the confirmation. Full multi-host contract: `references/preview.md`.
+3. **Preview / open a doc — determine your ONE surface FIRST (once per session).** Before opening anything, pick where to focus, stop at first match: **`OK_DESKTOP_TERMINAL` set** (check your env — `echo "$OK_DESKTOP_TERMINAL"`) → OK Desktop's own terminal → `ok open <name>` (switches this window) · have `preview_*` → Claude Code Desktop pane · have a URL-navigation/browser tool → Cursor/Codex → `preview_url` then navigate it · else plain CLI → `ok open <name>`. `ok open <name>` opens a **doc or folder** (auto-detected — no `--folder`); add `--skill <name>` for a skill. The `previewUrl` field is a route id, **not** your open mechanism — don't hand it to a browser just because you saw it. Don't `preview_screenshot` to confirm edits. Full Step-0 procedure + per-surface how-to: `references/preview.md`.
4. **Workflow guides:** `workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' })` returns a procedural guide, not data. Use it when the work fits the layer.
5. **Direct questions:** a plain business question ("which customers…", "what did we decide about…") routes to `search` / `exec` + a cited chat answer — no "research" keyword needed. Persist only when durable + multi-doc + not already covered, and *offer* first. See `references/corpus-qa.md`.
6. **Authoring or improving a skill** ("write/make a skill", "improve this skill", "turn this into a skill"): STOP and invoke the **`open-knowledge-write-skill`** skill — it owns scope choice (project vs global), the SKILL.md contract, evaluation, and install; don't improvise from this skill. Author through the `skill` target (`write({ skill })`), never a raw `.ok/skills/…` document. **Never read, diff, or edit the installed projections under `.claude/skills/` · `.cursor/skills/` · `.codex/skills/` · `.opencode/skills/` · `.agents/skills/`** — `install` generates them and overwrites them on the next sync; they are NOT source of truth.
diff --git a/packages/server/assets/skills/project/references/anti-patterns.md b/packages/server/assets/skills/project/references/anti-patterns.md
index d0e50cce9..13ad00033 100644
--- a/packages/server/assets/skills/project/references/anti-patterns.md
+++ b/packages/server/assets/skills/project/references/anti-patterns.md
@@ -14,7 +14,7 @@
| Wait for the server to tell you to open preview | Skip the session-start preview open and wait for the `attach-preview-once` hint | Open the preview browser at session start; the hint is a fallback when you didn't |
| Ignore the attach hint | Skip the `warning: { action: "attach-preview-once" }` hint in write-tool responses | Open the preview when the hint fires (`preview_start`, or `preview_url`); otherwise do nothing |
| Make the Claude Code Desktop preview work | Read / diagnose / edit `.claude/launch.json` (host-managed config) | Call `preview_start("open-knowledge-ui")` and nothing else; the OK lock-collision proxy bridges any port mismatch transparently |
-| Open a doc in the app from the Claude Code CLI | Print the `previewUrl` / `openknowledge://` string for the user to click | Run `ok open <doc>` — it opens the OK Desktop app (folders open in the browser), with browser fallback |
+| Open a doc/folder/skill in the app from a CLI | Print the `previewUrl` / `openknowledge://` string for the user to click | Run `ok open <name>` (doc or folder, auto-detected; `--skill <name>` for a skill) — deep-links into OK Desktop, browser fallback |
| Reference another doc | `` `[text](./page.md)` `` (backticked) or HTML `<a>` | `[text](./page.md)` (raw markdown) |
| Embed an image | `<img src="...">` (HTML), a `localhost:<port>` / `preview_url` server URL, or hot-linked external URL | Fetch + save locally + doc-relative `![meaningful alt](./assets/images/path)` |
| Write a factual claim in a KB doc | plausible prose without citation, OR inline `[source](https://URL)` | `ingest` the source first, then cite the local path per Grounding |
diff --git a/packages/server/assets/skills/project/references/preview.md b/packages/server/assets/skills/project/references/preview.md
index 4262d79d7..920e33250 100644
--- a/packages/server/assets/skills/project/references/preview.md
+++ b/packages/server/assets/skills/project/references/preview.md
@@ -1,10 +1,11 @@
# Preview — full multi-host contract
## Contents
+- **Step 0 — determine your ONE focus surface before opening anything (the load-bearing check)**
- Re-navigation and end-of-turn discipline
- `previewUrl` is a route, not a URL
- The three first-class apps (Claude Code Desktop, Cursor, Codex desktop)
-- Claude Code CLI track (no browser)
+- Any-CLI track — Claude Code / Codex / Cursor CLI / OpenCode, no browser → `ok open`
- Four attach signals
- `previewUrl: null` semantics, server lifecycle, read-only mirror, no-screenshots
@@ -16,7 +17,18 @@ The user watches your edits land in a live browser preview. Open it once at sess
**`previewUrl` is a route, not a URL to open.** Every read response (per-doc, on `exec` / `search` / `links` rows) and every write response carries a `previewUrl` — a route fragment like `/#/specs/foo/SPEC`, with **no scheme, host, or port**. It identifies *which doc* to preview, not a URL to hand a browser by itself. Never construct or guess preview URLs.
-**OK ships first-class preview support for three apps — Claude Code Desktop, Cursor, and the Codex desktop app — plus the Claude Code CLI on a separate track (below). Make the preview seamless in each.** Match on the tool you actually have (capability, not host name): if a tool can navigate to a URL, it counts as an in-app browser. The three apps map to:
+### Step 0 — figure out your ONE focus surface BEFORE you open anything
+
+Your host doesn't change mid-session, so determine this **once**, the first time you're asked to open/show/preview a doc, and use that one surface for the rest of the session. Run the checks **top-to-bottom and stop at the first match** — earlier rungs win:
+
+1. **Is `OK_DESKTOP_TERMINAL` set in your environment?** You're a shell agent — actually check it (`echo "$OK_DESKTOP_TERMINAL"`, or read your env), don't assume. **Set → you're inside the OK Desktop app's own terminal.** Open a doc or folder with `ok open <name>` (auto-detected; `--skill <name>` for a skill) — it switches THIS window to the target. **Never resolve a preview URL here.** (This rung is the one agents miss most — check the env first, before anything else.)
+2. **Do you have `preview_*` tools** (`preview_start` / `preview_eval`)? → **Claude Code Desktop** → drive its pane (rung details below).
+3. **Do you have any URL-navigation / in-app browser tool** (Cursor `Navigate`, Codex `@Browser`, or `browser` / `open_url` / `view_url` / …)? → **Cursor / Codex desktop** → `preview_url` once, then navigate that browser to the `url`.
+4. **None of the above** → you're a **plain CLI** (Claude Code CLI, Codex CLI, Cursor CLI, OpenCode, any shell agent) → `ok open <name>` for a doc or folder (auto-detected; `--skill <name>` for a skill); deep-links a separate OK Desktop window, system browser only if no desktop.
+
+Decide once; then every "open / show / preview this doc" this session uses that surface's mechanism. **The `previewUrl` field in tool responses is a route id, not your open mechanism** — seeing it is not a reason to hand it to a browser. The rest of this section is the per-surface "how" for whichever rung you landed on.
+
+**OK ships first-class preview support for three apps — Claude Code Desktop, Cursor, and the Codex desktop app — plus any CLI (Claude Code CLI, Codex CLI, Cursor CLI, OpenCode, …) on a separate `ok open` track (below). Make the preview seamless in each.** Match on the tool you actually have (capability, not host name): if a tool can navigate to a URL, it counts as an in-app browser; if nothing can, you're a CLI → `ok open`. The three apps map to:
- **Claude Code Desktop — you have `preview_*` tools** (e.g. `preview_start` + `preview_eval`) → **First open of the session:** to land directly on a doc, arm it first with `preview_url({ armPaneTarget: true, document })` (or `folder`), then `preview_start("open-knowledge-ui")` — `ok ui` redirects the base-open straight to the armed route, so the pane opens on the doc, not root. Plain `preview_start` (no arm) opens at root. **Moving between docs once the pane is open: do it in one `preview_eval` step — set `window.location.hash` to the target's route fragment from the response `previewUrl`, the part from `#` on (e.g. `window.location.hash = '#/specs/foo/SPEC'`).** That drives the SPA router directly. Arm + `preview_start` only redirects a *fresh* open; it can't move an already-open pane (`preview_start` reuses the live process without reloading), so use `preview_eval` there. Don't read or edit `.claude/launch.json` — host-managed; the OK lock-collision proxy handles the UI-already-running case. If `preview_start` fails, report it; don't "fix" `launch.json`.
- **Cursor / Codex desktop — no `preview_*` tool, but you have an in-app / built-in browser tool** → call `preview_url` once for the **exact** target (`document` for a doc, `folder` for a folder) and navigate your **in-app browser** straight to the returned `url`. Open that deep URL directly — never the root then navigate; omit both args only for the root. Drive the tool your host gives you:
@@ -25,7 +37,13 @@ The user watches your edits land in a live browser preview. Open it once at sess
- **Any other host** with a URL-navigation tool (`browser`, `view_url`, `open_url`, `web.browse`, …) → navigate it to the `url`. **This is also the fallback when a named tool above isn't present under that exact name** (hosts rename tools): match on the capability, not the name. If no URL-navigation tool exists at all, drop to the Claude Code CLI track below.
- **Honor `autoOpen`** (on `preview_url`, or on `warning` for write tools). If `false`, do not open or refresh any preview UI; surface the URL only if asked.
-**Claude Code CLI — a separate track (no browser).** The CLI is pure stdio: don't open or fake a browser. For an "open `<doc>`/`<folder>`" request, run **`ok open <doc>`** (`--folder` for a folder) — it deep-links the doc into OK Desktop (folders open in the browser); an action you run, not a URL to print. Any other pure-stdio host with **no** URL-navigation tool is on this track too — but if you *do* have a tool that navigates to a URL, use the in-app branch above, not this track. The Codex **CLI**, **IDE extension**, and **Cloud** also live here (web search only, no localhost browser). No `ok` on PATH or no shell → `preview_url`, then `open <url>` in the system browser as a last resort, and say so plainly. The system browser is the fallback, never the default.
+**Any CLI — a separate track (no browser).** **Claude Code CLI, Codex CLI, Cursor CLI, OpenCode — any pure-stdio / shell agent with no in-app browser tool — uses `ok open`, never a preview URL.** The rule is capability, not vendor: no tool that navigates a URL → you're on this track.
+
+- **`ok open <name>`** — opens a **doc or folder** in the OK Desktop app. The type is auto-detected (a directory on disk → folder, otherwise a doc), so **`--folder` is not needed** (it stays only as an explicit override for a folder that doesn't exist on disk yet). An action you run, not a URL to print.
+- **`ok open <skill-name> --skill [--scope project|global]`** — opens a **skill** in the skill editor (skills are addressed by name + scope, not a content path, so they need the flag).
+- All three deep-link into OK Desktop when a bundle is installed, and fall back to the browser UI (`ok ui`) otherwise. No `ok` on PATH or no shell → `preview_url`, then `open <url>` in the system browser as a last resort, and say so plainly. The system browser is the fallback, never the default.
+
+(The same vendors' *desktop apps* with a built-in browser — Cursor, Codex desktop — are NOT here; they navigate their own browser per the in-app branch above. Codex **IDE extension** / **Cloud** are web-search-only → they're on this CLI track too.) **Running inside the OK Desktop built-in terminal (the `OK_DESKTOP_TERMINAL` env var is set)? Same track — `ok open <name>` re-targets the window you're already in** (switches that window to the doc/folder; no second window, no need to raise it since it's already frontmost). Don't resolve preview URLs in that case; `ok open` is the whole answer.
**Opening or reading a file IS a preview navigation.** On any "open `<file>`" / "read `<file>`" request, navigate the browser to that doc's `previewUrl` route from the tool response — not a separate fetch, not a fresh system-browser launch.
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index e4676c284..61a31108e 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -266,7 +266,12 @@ export { getCurrentMcpLogger, McpLogger, runWithMcpLogger } from './mcp/logger.t
export { installPrettyZodErrors } from './mcp/pretty-zod-errors.ts';
export { buildExecResult, type ExecStructuredResult } from './mcp/tools/exec.ts';
export { registerAllTools } from './mcp/tools/index.ts';
-export { encodeDocName, encodeFolderRoute, resolveUiInfo } from './mcp/tools/preview-url.ts';
+export {
+ encodeDocName,
+ encodeFolderRoute,
+ encodeSkillRoute,
+ resolveUiInfo,
+} from './mcp/tools/preview-url.ts';
export {
createMcpHttpHandler,
type McpHttpHandler,
diff --git a/packages/server/src/mcp/tools/get-preview-url.test.ts b/packages/server/src/mcp/tools/get-preview-url.test.ts
index f001308a2..7fe7b4038 100644
--- a/packages/server/src/mcp/tools/get-preview-url.test.ts
+++ b/packages/server/src/mcp/tools/get-preview-url.test.ts
@@ -37,6 +37,7 @@ interface EnsureDeps {
offCwdResolverDeps?: OffCwdResolverDeps;
ensureSingleFileSession?: (absFile: string) => Promise<boolean>;
resolveUserAutoOpen?: () => boolean;
+ isDesktopTerminal?: boolean;
}
function captureRegistration(
@@ -125,6 +126,100 @@ describe('preview_url tool — UI running', () => {
expect(readArmedPaneTarget(resolveLockDir(cwd))).toBe('#/specs/foo/');
});
+ describe('isDesktopTerminal steer (OK Desktop built-in terminal)', () => {
+ test('document: response leads with `ok open <doc>` and tells the agent not to navigate the URL', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ document: 'specs/foo/SPEC' });
+ const text = result.content[0]?.text ?? '';
+ expect(text).toContain('ok open specs/foo/SPEC');
+ expect(text).toMatch(/Don't navigate the URL|reference only/);
+ expect(result.structuredContent?.running).toBe(true);
+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo/SPEC');
+ });
+
+ test('folder: steers to `ok open <folder>`', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ folder: 'specs/foo' });
+ expect(result.content[0]?.text ?? '').toContain('ok open specs/foo');
+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo');
+ });
+
+ test('skill default scope (project): steers to `ok open <name> --skill` (no --scope)', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ skill: { name: 'trip-log' } });
+ expect(result.content[0]?.text ?? '').toContain('ok open trip-log --skill');
+ expect(result.content[0]?.text ?? '').not.toContain('--scope');
+ expect(result.structuredContent?.okOpenCommand).toBe('ok open trip-log --skill');
+ });
+
+ test('skill --scope global: steers to `ok open <name> --skill --scope global`', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ skill: { name: 'trip-log', scope: 'global' } });
+ expect(result.content[0]?.text ?? '').toContain('ok open trip-log --skill --scope global');
+ expect(result.structuredContent?.okOpenCommand).toBe(
+ 'ok open trip-log --skill --scope global',
+ );
+ });
+
+ test('no target (root): no steer — nothing to `ok open`', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({});
+ expect(result.content[0]?.text ?? '').not.toContain('ok open');
+ });
+
+ test('NOT a desktop terminal (default): no steer — plain Preview URL', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd);
+ const result = await handler({ document: 'specs/foo/SPEC' });
+ expect(result.content[0]?.text ?? '').not.toContain('ok open');
+ expect(result.structuredContent?.okOpenCommand ?? null).toBeNull();
+ });
+
+ test('desktop terminal + no UI running: steer + okOpenCommand still fire (ok open does not need the UI)', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ document: 'specs/foo/SPEC' });
+ expect(result.structuredContent?.running).toBe(false);
+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo/SPEC');
+ expect(result.content[0]?.text ?? '').toContain('ok open specs/foo/SPEC');
+ });
+
+ test('document with a space: okOpenCommand shell-quotes the path', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ document: 'notes/My Doc' });
+ expect(result.structuredContent?.okOpenCommand).toBe("ok open 'notes/My Doc'");
+ });
+
+ test('document with an embedded single quote: okOpenCommand POSIX-escapes it', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ bindTestUiLock(cwd);
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ document: "Q&A/what's new" });
+ expect(result.structuredContent?.okOpenCommand).toBe("ok open 'Q&A/what'\\''s new'");
+ });
+
+ test('desktop terminal + no UI + folder: okOpenCommand still fires', async () => {
+ const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
+ const handler = captureRegistration(cwd, BASE_CONFIG, { isDesktopTerminal: true });
+ const result = await handler({ folder: 'specs/foo' });
+ expect(result.structuredContent?.running).toBe(false);
+ expect(result.structuredContent?.okOpenCommand).toBe('ok open specs/foo');
+ });
+ });
+
test('docName + folder together is rejected (mutually exclusive)', async () => {
const cwd = mkdtempSync(join(tmpdir(), 'ok-get-preview-url-'));
bindTestUiLock(cwd);
diff --git a/packages/server/src/mcp/tools/get-preview-url.ts b/packages/server/src/mcp/tools/get-preview-url.ts
index 5f09a01cc..3949eff0a 100644
--- a/packages/server/src/mcp/tools/get-preview-url.ts
+++ b/packages/server/src/mcp/tools/get-preview-url.ts
@@ -52,6 +52,7 @@ const DESCRIPTION = [
interface GetPreviewUrlDeps {
config: ConfigOrResolver;
resolveCwd: (explicit?: string) => Promise<string>;
+ isDesktopTerminal?: boolean;
serverUrl?: ServerUrlOrResolver;
uiBindWait?: { timeoutMs?: number; pollIntervalMs?: number };
offCwdResolverDeps?: OffCwdResolverDeps;
@@ -126,6 +127,13 @@ const OutputSchema = outputSchemaWithText({
.describe(
'User-scoped preview-auto-open preference (`appearance.preview.autoOpen`). When `true`, the agent should route the preview using capability-based routing (in-app browser if available, system browser as fallback). When `false`, the user is managing their own preview view (OK Desktop window, a browser tab they opened, etc.) — the agent must NOT open or refresh any preview UI, and should surface this URL only on direct user ask. Resolved fresh on every call; defaults to `true`.',
),
+ okOpenCommand: z
+ .string()
+ .nullable()
+ .optional()
+ .describe(
+ 'Machine-readable form of the desktop-terminal steer: when this MCP server runs inside OK Desktop’s built-in terminal AND a doc/folder/skill target was given, the exact `ok open …` command to run to focus it in the OK Desktop window. Prefer running it over navigating `url`. `null`/absent in every other context (navigate `url` per your host instead).',
+ ),
});
const NO_UI_SERVER_RUNNING_MESSAGE =
@@ -165,6 +173,11 @@ function isServerLive(lockDir: string): boolean {
}
}
+function shellQuoteArg(arg: string): string {
+ if (/^[A-Za-z0-9._/@%+-]+$/.test(arg)) return arg;
+ return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
export function register(server: ServerInstance, deps: GetPreviewUrlDeps): void {
server.registerTool(
'preview_url',
@@ -257,6 +270,18 @@ export function register(server: ServerInstance, deps: GetPreviewUrlDeps): void
? `#/${encodeSkillRoute(args.skill.scope ?? 'project', args.skill.name)}`
: null;
+ const okOpenCommand = args.document
+ ? `ok open ${shellQuoteArg(args.document)}`
+ : args.folder
+ ? `ok open ${shellQuoteArg(args.folder)}`
+ : args.skill
+ ? `ok open ${args.skill.name} --skill${args.skill.scope === 'global' ? ' --scope global' : ''}`
+ : null;
+ const desktopTerminalSteer =
+ deps.isDesktopTerminal && okOpenCommand
+ ? `You're in the OK Desktop terminal — run \`${okOpenCommand}\` to focus this in the OK Desktop window. Don't navigate the URL below or open a browser; it's for reference only.\n\n`
+ : '';
+
if (args.armPaneTarget && routeFragment) {
try {
armPaneTarget(lockDir, routeFragment);
@@ -302,21 +327,23 @@ export function register(server: ServerInstance, deps: GetPreviewUrlDeps): void
const hint = isServerLive(lockDir)
? NO_UI_SERVER_RUNNING_MESSAGE
: `${NO_SERVER_MESSAGE}${autoStartDisabled ? AUTOSTART_DISABLED_NOTE : ''}`;
- return textPlusStructured(`${hint}${armNote}`, {
+ return textPlusStructured(`${desktopTerminalSteer}${hint}${armNote}`, {
url: null,
baseUrl: null,
running: false,
autoOpen,
+ okOpenCommand: deps.isDesktopTerminal ? okOpenCommand : null,
});
}
const url = routeFragment ? `${baseUrl}/${routeFragment}` : baseUrl;
- return textPlusStructured(`Preview URL: ${url}${armNote}`, {
+ return textPlusStructured(`${desktopTerminalSteer}Preview URL: ${url}${armNote}`, {
url,
baseUrl,
running: true,
autoOpen,
+ okOpenCommand: deps.isDesktopTerminal ? okOpenCommand : null,
});
},
);
diff --git a/packages/server/src/mcp/tools/index.ts b/packages/server/src/mcp/tools/index.ts
index 6b641118b..37293e17c 100644
--- a/packages/server/src/mcp/tools/index.ts
+++ b/packages/server/src/mcp/tools/index.ts
@@ -31,6 +31,7 @@ interface RegisterAllToolsOptions {
config: ConfigOrResolver;
identityRef?: { current: AgentIdentity };
logger?: McpLogger;
+ isDesktopTerminal?: boolean;
}
export function registerAllTools(server: ServerInstance, opts: RegisterAllToolsOptions): void {
@@ -142,6 +143,7 @@ export function registerAllTools(server: ServerInstance, opts: RegisterAllToolsO
config: opts.config,
resolveCwd: named('preview_url'),
serverUrl: opts.serverUrl,
+ isDesktopTerminal: opts.isDesktopTerminal,
...(opts.serverUrl ? { ensureSingleFileSession: createEnsureSingleFileSession() } : {}),
});
registerConflicts(registrationServer, {