Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex e500fb8bc..06418b60c 100644--- a/packages/cli/src/commands/init.ts+++ b/packages/cli/src/commands/init.ts@@ -892,6 +892,76 @@ doneecho "OpenKnowledge: install OK Desktop or Node.js 24+, then restart your editor" >&2exit 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 PORTexec 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.tsindex 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.tsindex 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';