Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): Windows-launchable launch.json ok-ui entry (#2515)

mike-inkeepe092e7164056
diff --git a/.changeset/windows-launch-json-ui-chain.md b/.changeset/windows-launch-json-ui-chain.md
new file mode 100644
index 000000000..4bdd201ba
--- /dev/null
+++ b/.changeset/windows-launch-json-ui-chain.md
@@ -0,0 +1,5 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Make the `open-knowledge-ui` entry in `.claude/launch.json` launchable on Windows. Previously `ok init` always wrote a `/bin/sh` chain, so Claude Code Desktop's preview pane could not start the OpenKnowledge UI on Windows (there is no `/bin/sh`). On Windows, `ok init` now scaffolds a `powershell -NoProfile -NonInteractive -Command <chain>` entry that resolves the npm-global `ok.cmd` shim first, then `npx.cmd`, then common version-manager/installer paths, and runs `ok start --ui-port` so the opened folder gets its own collab server. The `ok start` launch.json repair sweep now recognizes both platforms' canonical shapes on every OS, so a `launch.json` committed on one platform is never rewritten back and forth by the other, and custom entries are still preserved.
diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts
index b1e79d187..2c4b16eb7 100644
--- a/packages/cli/src/commands/init.test.ts
+++ b/packages/cli/src/commands/init.test.ts
@@ -51,6 +51,7 @@ import {
initCommand,
LAUNCH_UI_CHAIN_SENTINEL,
LAUNCH_UI_CHAIN_V1,
+ LAUNCH_UI_WIN_CHAIN_SENTINEL,
MANAGED_FILE_BUILDERS,
readExistingMcpEntry,
resolveInitSkillEnablement,
@@ -58,6 +59,7 @@ import {
resolveRequestedContentDir,
resolveSharingMode,
runInit,
+ scaffoldLaunchJson,
writeEditorMcpConfig,
writeUserMcpConfigs,
} from './init.ts';
@@ -1097,6 +1099,39 @@ describe('runInit', () => {
expect(result.launchJson).toBeUndefined();
expect(existsSync(join(testDir, '.claude', 'launch.json'))).toBe(false);
});
+
+ it('emits the powershell `# ok-ui-win-v1` chain on Windows', () => {
+ // Windows has no `/bin/sh`, so the preview pane cannot launch the posix
+ // chain. `platformName` is injected (rather than spoofing the ambient
+ // `process.platform`) since a machine always writes its own platform's
+ // shape; the option exists purely to pin either shape under test.
+ const result = scaffoldLaunchJson(testDir, { platformName: 'win32' });
+ expect(result.action).toBe('created');
+
+ const parsed = JSON.parse(readFileSync(join(testDir, '.claude', 'launch.json'), 'utf-8'));
+ expect(parsed.configurations).toHaveLength(1);
+ const entry = parsed.configurations[0];
+ expect(entry.name).toBe('open-knowledge-ui');
+ expect(entry.runtimeExecutable).toBe('powershell');
+ expect(entry.runtimeArgs.slice(0, 3)).toEqual(['-NoProfile', '-NonInteractive', '-Command']);
+ const chain = entry.runtimeArgs[3];
+ expect(chain).toContain(LAUNCH_UI_WIN_CHAIN_SENTINEL);
+ expect(chain).toContain('start --ui-port');
+ expect(chain).not.toContain('/bin/sh');
+ // The body must carry zero double-quote characters: it travels as one
+ // argv element through the host's Windows argument-quoting layer, and any
+ // `"` would be mangled there.
+ expect(chain).not.toContain('"');
+ expect(entry.port).toBe(LAUNCH_JSON_PORT);
+ expect(entry.autoPort).toBe(true);
+ });
+
+ it('emits the posix `/bin/sh` chain when the platform is macOS', () => {
+ const result = scaffoldLaunchJson(testDir, { platformName: 'darwin' });
+ expect(result.action).toBe('created');
+ const parsed = JSON.parse(readFileSync(join(testDir, '.claude', 'launch.json'), 'utf-8'));
+ assertChainEntry(parsed.configurations[0]);
+ });
});
// -----------------------------------------------------------------------
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index e500fb8bc..06418b60c 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -892,6 +892,76 @@ done
echo "OpenKnowledge: install OK Desktop or Node.js 24+, then restart your editor" >&2
exit 127`;
+/**
+ * Version sentinel for the Windows published-mode launch.json recipe — the
+ * PowerShell sibling of `LAUNCH_UI_CHAIN_SENTINEL`. First line of the chain,
+ * doubling as a PowerShell comment. Bump the suffix (`win-v2`, …) on any
+ * structurally-different chain so the repair sweep rewrites stale text forward.
+ */
+export const LAUNCH_UI_WIN_CHAIN_SENTINEL = '# ok-ui-win-v1';
+
+/**
+ * Windows published-mode `.claude/launch.json` recipe — the PowerShell member
+ * of the two-shape canonical set (Unix sibling: `LAUNCH_UI_CHAIN_V1`). Claude
+ * Code Desktop's preview pane spawns this to bring the folder's editor up on
+ * Windows, where `/bin/sh` does not exist. Mirrors the proven `# ok-mcp-win-v1`
+ * chain (`CHAIN_WIN_V1` in editors.ts) — resolves the npm-global `ok.cmd` shim
+ * first, then `npx.cmd` from PATH, then explicit version-manager/installer
+ * dirs — but runs `ok start --ui-port`, not `ok mcp`, so the opened folder
+ * gets its OWN collab server (the worktree fix). No OK Desktop bundle branches:
+ * OK Desktop does not ship on Windows, so `npm i -g @inkeep/open-knowledge` is
+ * the primary install persona, and the pinned global shim outranks `npx
+ * @latest` so the launched UI resolves to the SAME installed version as the
+ * user's hand-run `ok`.
+ *
+ * Port handling mirrors the Unix chain: capture the pane's watched `PORT` env
+ * into `$UIPORT`, defaulting to `LAUNCH_JSON_PORT` (the same port the pane
+ * probes) when `PORT` is absent, then clear `PORT` so the auto-spawned collab
+ * server kernel-allocates instead of fighting its UI sibling for the env port.
+ * `--ui-port` is always passed — that arms `ok start`'s
+ * connect-instead-of-exit-1 fallback so one committed recipe is safe on both
+ * the main checkout and a fresh worktree.
+ *
+ * Each PowerShell detail is load-bearing exactly as documented on `CHAIN_WIN_V1`:
+ * `powershell` (5.1, preinstalled everywhere) not `cmd`/`pwsh`; `-NoProfile
+ * -NonInteractive` for a deterministic, fail-loud spawn; zero double-quote
+ * characters in the body (single-quoted literals + `Join-Path` only) so the
+ * script survives the host's argument-quoting layer as one argv element;
+ * `.cmd` shims only (a `.ps1` re-enters execution policy); `exit
+ * $LASTEXITCODE` after each invocation (PowerShell has no `exec`); null-guarded
+ * env probes (`Join-Path` on an unset var throws); and the PATHEXT guard on
+ * line 2 — Electron hosts spawn with a PATHEXT that omits `.CMD`, which makes
+ * `& <path>\ok.cmd` a SILENT no-op, so the guard prepends the standard
+ * executable extensions.
+ */
+export const LAUNCH_UI_WIN_CHAIN_V1 = `${LAUNCH_UI_WIN_CHAIN_SENTINEL}
+if ($env:PATHEXT -notmatch 'CMD') { $env:PATHEXT = '.COM;.EXE;.BAT;.CMD;' + $env:PATHEXT }
+$UIPORT = if ($env:PORT) { $env:PORT } else { '${LAUNCH_JSON_PORT}' }
+Remove-Item Env:PORT -ErrorAction SilentlyContinue
+if ($env:APPDATA) {
+ $shim = Join-Path $env:APPDATA 'npm\\ok.cmd'
+ if (Test-Path -LiteralPath $shim -PathType Leaf) { & $shim start --ui-port $UIPORT; exit $LASTEXITCODE }
+}
+$ok = Get-Command ok.cmd -CommandType Application -ErrorAction SilentlyContinue
+if ($ok) { & $ok.Source start --ui-port $UIPORT; exit $LASTEXITCODE }
+$npx = Get-Command npx.cmd -CommandType Application -ErrorAction SilentlyContinue
+if ($npx) { & $npx.Source -y '@inkeep/open-knowledge@latest' start --ui-port $UIPORT; exit $LASTEXITCODE }
+$dirs = @()
+if ($env:ProgramFiles) { $dirs += Join-Path $env:ProgramFiles 'nodejs' }
+if ($env:NVM_SYMLINK) { $dirs += $env:NVM_SYMLINK }
+if ($env:LOCALAPPDATA) {
+ $dirs += Join-Path $env:LOCALAPPDATA 'fnm\\aliases\\default'
+ $dirs += Join-Path $env:LOCALAPPDATA 'Volta\\bin'
+ $dirs += Join-Path $env:LOCALAPPDATA 'pnpm'
+}
+if ($env:USERPROFILE) { $dirs += Join-Path $env:USERPROFILE 'scoop\\shims' }
+foreach ($d in $dirs) {
+ $probe = Join-Path $d 'npx.cmd'
+ if (Test-Path -LiteralPath $probe -PathType Leaf) { & $probe -y '@inkeep/open-knowledge@latest' start --ui-port $UIPORT; exit $LASTEXITCODE }
+}
+[Console]::Error.WriteLine('OpenKnowledge: install Node.js 24+ (npm i -g @inkeep/open-knowledge), then restart your editor')
+exit 127`;
+
type LaunchJsonAction = 'created' | 'merged' | 'failed';
export interface LaunchJsonResult {
@@ -927,12 +997,17 @@ export function scaffoldLaunchJson(
// port, passes via `PORT`, still routes through the proxy branch. Full pairing
// rationale on `LAUNCH_JSON_PORT` in `ui.ts`.
//
- // The recipe runs `ok start` (not bare `ok ui`) via a `/bin/sh` chain so the
- // opened folder — crucially, a worktree — gets its OWN collab server, not just
- // a UI. `ok start` connects-instead-of-erroring on a live lock (the `--ui-port`
- // path), so the same committed recipe is correct on both the main checkout and
- // a fresh worktree. Dev mode pins the chain's exec to the local CLI dist; both
- // modes carry the `# ok-ui-v1` sentinel so the repair sweep recognizes them.
+ // The recipe runs `ok start` (not bare `ok ui`) so the opened folder —
+ // crucially, a worktree — gets its OWN collab server, not just a UI. `ok
+ // start` connects-instead-of-erroring on a live lock (the `--ui-port` path),
+ // so the same committed recipe is correct on both the main checkout and a
+ // fresh worktree. The published recipe uses the local platform's interpreter:
+ // a `/bin/sh` chain (`# ok-ui-v1`) on macOS/Linux, a `powershell` chain
+ // (`# ok-ui-win-v1`) on Windows, since `/bin/sh` does not exist there and the
+ // preview pane could not otherwise launch the UI. Dev mode stays `/bin/sh`
+ // (monorepo development is Unix-only) and pins the chain's exec to the local
+ // CLI dist. Every shape carries its platform's sentinel so the repair sweep
+ // recognizes them.
//
// `resolveDevCliDistPath()` is resolved LAZILY (dev branch only) — it throws
// when the repo root can't be inferred, which is the normal case for the
@@ -941,6 +1016,9 @@ export function scaffoldLaunchJson(
UIPORT="\${PORT:-${LAUNCH_JSON_PORT}}"
unset PORT
exec node "${resolveDevCliDistPath()}" start --ui-port "$UIPORT"`;
+ // Writers never set `platformName`; a machine always emits its own platform's
+ // shape. Tests inject it to pin either shape on any host.
+ const platformName = installOptions.platformName ?? process.platform;
const entry: {
name: string;
runtimeExecutable: string;
@@ -956,13 +1034,21 @@ exec node "${resolveDevCliDistPath()}" start --ui-port "$UIPORT"`;
port: LAUNCH_JSON_PORT,
autoPort: true,
}
- : {
- name: LAUNCH_CONFIG_NAME,
- runtimeExecutable: '/bin/sh',
- runtimeArgs: ['-l', '-c', LAUNCH_UI_CHAIN_V1],
- port: LAUNCH_JSON_PORT,
- autoPort: true,
- };
+ : platformName === 'win32'
+ ? {
+ name: LAUNCH_CONFIG_NAME,
+ runtimeExecutable: 'powershell',
+ runtimeArgs: ['-NoProfile', '-NonInteractive', '-Command', LAUNCH_UI_WIN_CHAIN_V1],
+ port: LAUNCH_JSON_PORT,
+ autoPort: true,
+ }
+ : {
+ name: LAUNCH_CONFIG_NAME,
+ runtimeExecutable: '/bin/sh',
+ runtimeArgs: ['-l', '-c', LAUNCH_UI_CHAIN_V1],
+ port: LAUNCH_JSON_PORT,
+ autoPort: true,
+ };
try {
assertProjectPathSafe(configPath, cwd);
diff --git a/packages/cli/src/commands/repair-launch-json.test.ts b/packages/cli/src/commands/repair-launch-json.test.ts
index f6a03f8c8..b2933bca8 100644
--- a/packages/cli/src/commands/repair-launch-json.test.ts
+++ b/packages/cli/src/commands/repair-launch-json.test.ts
@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
-import { LAUNCH_UI_CHAIN_SENTINEL, LAUNCH_UI_CHAIN_V1 } from './init.ts';
+import { LAUNCH_UI_CHAIN_SENTINEL, LAUNCH_UI_CHAIN_V1, LAUNCH_UI_WIN_CHAIN_V1 } from './init.ts';
import {
classifyLaunchJsonEntry,
type LaunchJsonRepairLogEvent,
@@ -45,6 +45,18 @@ const LEGACY_BARE_WITH_Y_ENTRY = {
autoPort: true,
};
+// Current canonical Windows recipe — the `# ok-ui-win-v1` `powershell` chain a
+// Windows `ok init` commits. A macOS/Linux checkout that reads this shared file
+// MUST classify it canonical, or the two platforms' startup repair sweeps would
+// rewrite the committed entry back and forth forever.
+const CANONICAL_WIN_ENTRY = {
+ name: 'open-knowledge-ui',
+ runtimeExecutable: 'powershell',
+ runtimeArgs: ['-NoProfile', '-NonInteractive', '-Command', LAUNCH_UI_WIN_CHAIN_V1],
+ port: 50219,
+ autoPort: true,
+};
+
/** Assert a rewritten entry is the current canonical chain shape. */
function expectCanonicalChain(entry: { runtimeExecutable: string; runtimeArgs: string[] }): void {
expect(entry.runtimeExecutable).toBe('/bin/sh');
@@ -58,6 +70,52 @@ describe('classifyLaunchJsonEntry', () => {
expect(classifyLaunchJsonEntry(CANONICAL_ENTRY)).toBe('canonical');
});
+ it('returns "canonical" for the current Windows `# ok-ui-win-v1` powershell chain', () => {
+ expect(classifyLaunchJsonEntry(CANONICAL_WIN_ENTRY)).toBe('canonical');
+ });
+
+ it('recognizes BOTH platform canonicals regardless of the host platform (no ping-pong)', () => {
+ // The load-bearing mutual-recognition invariant: a macOS user and a Windows
+ // user sharing one committed `.claude/launch.json` must both see the other's
+ // committed shape as canonical, so neither startup repair sweep rewrites it.
+ // `classifyLaunchJsonEntry` is platform-independent by construction — assert
+ // it on every host, spoofing `process.platform` both ways to prove it never
+ // consults the ambient platform.
+ const originalPlatform = process.platform;
+ try {
+ for (const spoofed of ['darwin', 'linux', 'win32'] as const) {
+ Object.defineProperty(process, 'platform', { value: spoofed, configurable: true });
+ expect(classifyLaunchJsonEntry(CANONICAL_ENTRY)).toBe('canonical');
+ expect(classifyLaunchJsonEntry(CANONICAL_WIN_ENTRY)).toBe('canonical');
+ }
+ } finally {
+ Object.defineProperty(process, 'platform', {
+ value: originalPlatform,
+ configurable: true,
+ });
+ }
+ });
+
+ it('returns "legacy-bare" for an older `# ok-ui-win-vN` powershell chain we no longer ship', () => {
+ expect(
+ classifyLaunchJsonEntry({
+ name: 'open-knowledge-ui',
+ runtimeExecutable: 'powershell',
+ runtimeArgs: ['-NoProfile', '-NonInteractive', '-Command', '# ok-ui-win-v0\nok start'],
+ }),
+ ).toBe('legacy-bare');
+ });
+
+ it('returns "preserved" for a foreign powershell command without our sentinel', () => {
+ expect(
+ classifyLaunchJsonEntry({
+ name: 'open-knowledge-ui',
+ runtimeExecutable: 'powershell',
+ runtimeArgs: ['-NoProfile', '-Command', 'Start-Process my-own-launcher'],
+ }),
+ ).toBe('preserved');
+ });
+
it('returns "legacy-bare" for the pre-D5 published `npx @latest ui` shape', () => {
expect(classifyLaunchJsonEntry(LEGACY_AT_LATEST_ENTRY)).toBe('legacy-bare');
});
@@ -259,6 +317,24 @@ describe('repairLaunchJson', () => {
expect(logEvents.filter((e) => e.event === 'launch-json-repair-applied')).toHaveLength(0);
});
+ it('leaves a Windows-committed canonical entry untouched on this host (no ping-pong)', () => {
+ // The sweep-level guarantee behind the classifier's mutual recognition: a
+ // `.claude/launch.json` committed by a Windows teammate must survive an
+ // `ok start` repair sweep on macOS/Linux with zero rewrite, and vice versa.
+ const configPath = writeLaunchJson({
+ version: '0.0.1',
+ configurations: [CANONICAL_WIN_ENTRY],
+ });
+ const before = readFileSync(configPath, 'utf-8');
+
+ const result = repairLaunchJson({ projectDir, logger });
+
+ expect(result.outcome.outcome).toBe('canonical');
+ expect(result.repairedCount).toBe(0);
+ expect(readFileSync(configPath, 'utf-8')).toBe(before);
+ expect(logEvents.filter((e) => e.event === 'launch-json-repair-applied')).toHaveLength(0);
+ });
+
it('preserves a @beta-pinned entry (user intent)', () => {
const configPath = writeLaunchJson({
version: '0.0.1',
diff --git a/packages/cli/src/commands/repair-launch-json.ts b/packages/cli/src/commands/repair-launch-json.ts
index 060dc6dd4..00fe24838 100644
--- a/packages/cli/src/commands/repair-launch-json.ts
+++ b/packages/cli/src/commands/repair-launch-json.ts
@@ -24,6 +24,7 @@ import {
LAUNCH_CONFIG_NAME,
LAUNCH_JSON_CANONICAL_ARGS,
LAUNCH_UI_CHAIN_SENTINEL,
+ LAUNCH_UI_WIN_CHAIN_SENTINEL,
type LaunchJsonResult,
scaffoldLaunchJson,
} from './init.ts';
@@ -48,15 +49,22 @@ export type LaunchJsonEntryClassification = 'canonical' | 'legacy-bare' | 'prese
* for direct unit testing. Unlike MCP config repair, launch.json has no
* namespace-ownership semantics, so custom command shapes are preserved.
*
- * - `canonical` — the current `# ok-ui-v1` `/bin/sh` chain; no repair.
+ * - `canonical` — the current `# ok-ui-v1` `/bin/sh` chain (macOS/Linux) OR the
+ * current `# ok-ui-win-v1` `powershell` chain (Windows); no repair. BOTH
+ * platforms' canonical shapes are recognized regardless of the CURRENT host
+ * platform: a committed `.claude/launch.json` written on one platform must
+ * classify as canonical on the other, or a macOS user and a Windows user
+ * sharing the repo would have their startup repair sweeps rewrite the shared
+ * file back and forth forever. Writers always EMIT the local platform's shape;
+ * this predicate only decides "leave it alone".
* - `legacy-bare` — an earlier npx-`ui` shape (any of `LEGACY_NPX_UI_FORMS`)
- * OR an older `# ok-ui-vN` chain we own but no longer ship; rewriting forward
- * to the current chain unwedges the worktree-no-collab-server hang (and, for
- * the bare-npx forms, npm's engine-aware stale-release downgrade).
- * - `preserved` — anything else: version-pinned npx, a foreign `/bin/sh`
- * command, `node /path/cli.mjs` dev mode, custom command, foreign-customized
- * args, or any shape we don't recognize. Left alone — preserving user intent
- * matters more than aggressive normalization.
+ * OR an older `# ok-ui-vN` / `# ok-ui-win-vN` chain we own but no longer ship;
+ * rewriting forward to the current chain unwedges the worktree-no-collab-server
+ * hang (and, for the bare-npx forms, npm's engine-aware stale-release downgrade).
+ * - `preserved` — anything else: version-pinned npx, a foreign `/bin/sh` or
+ * `powershell` command, `node /path/cli.mjs` dev mode, custom command,
+ * foreign-customized args, or any shape we don't recognize. Left alone —
+ * preserving user intent matters more than aggressive normalization.
*/
export function classifyLaunchJsonEntry(
entry: Record<string, unknown>,
@@ -73,6 +81,18 @@ export function classifyLaunchJsonEntry(
}
return 'preserved';
}
+ // Windows `powershell` chain — the same sentinel logic on `args[3]` (the
+ // `-Command` payload sits after `-NoProfile -NonInteractive -Command`). This
+ // branch is platform-independent by design (see the mutual-recognition note
+ // above): a Unix host must still see a Windows-committed entry as canonical.
+ if (entry.runtimeExecutable === 'powershell' && Array.isArray(entry.runtimeArgs)) {
+ const chain = entry.runtimeArgs[3];
+ if (typeof chain === 'string') {
+ if (chain.includes(LAUNCH_UI_WIN_CHAIN_SENTINEL)) return 'canonical';
+ if (/# ok-ui-win-v\d+/.test(chain)) return 'legacy-bare';
+ }
+ return 'preserved';
+ }
if (entry.runtimeExecutable === 'npx' && Array.isArray(entry.runtimeArgs)) {
for (const form of LEGACY_NPX_UI_FORMS) {
if (argsExactlyMatch(entry.runtimeArgs, form)) return 'legacy-bare';