Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
PRD-8107: Clean desktop data across platforms (#3638)
mike-inkeep22bb1ef284b8
diff --git a/.changeset/clean-desktop-uninstall-data.md b/.changeset/clean-desktop-uninstall-data.mdnew file mode 100644index 000000000..ee95aa344--- /dev/null+++ b/.changeset/clean-desktop-uninstall-data.md@@ -0,0 +1,5 @@+---+'@inkeep/open-knowledge': patch+---++Clean up OpenKnowledge Desktop state and updater caches during uninstall on macOS, Windows, and Linux.diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 6e9131ee3..934f718e1 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -34,7 +34,7 @@ How the app lands depends on your platform:- **Windows** — a per-user installer: the app lands under `%LOCALAPPDATA%\Programs\`, with no admin prompt. The installer itself adds the bundled `ok` CLI to your **user** `PATH` (a registry value under `HKCU\Environment`) and registers the `openknowledge://` URL scheme under `HKCU\Software\Classes` — both removed by its uninstaller. Your shell startup files are never touched.- **Linux** — a deb or rpm package: the app installs to `/opt/OpenKnowledge/`, and the package's post-install script symlinks `/usr/bin/ok`, `/usr/bin/open-knowledge`, and `/usr/bin/openknowledge` (plus a desktop entry that registers the `openknowledge://` scheme, and an AppArmor profile on Ubuntu 24.04+ so the Chromium sandbox keeps working). Your shell startup files are never touched.-On every platform the app writes app-level state and logs on launch. The table below shows the macOS locations; on Windows the same app-state files live under `%APPDATA%\OpenKnowledge\` and on Linux under `~/.config/OpenKnowledge/` (staged updates go to the matching per-user cache directory), while the `~/.ok/` paths are the same everywhere.+On every platform the app writes app-level state and logs on launch. The table below shows the macOS locations; on Windows the same app-state files live under `%APPDATA%\OpenKnowledge\` and staged updates under `%LOCALAPPDATA%\@inkeepopen-knowledge-desktop-updater\`. On Linux, app state defaults to `~/.config/OpenKnowledge/` and staged updates to `~/.cache/@inkeepopen-knowledge-desktop-updater/` (or the corresponding XDG config and cache directories). The `~/.ok/` paths are the same everywhere.| Path | What it is | Scope || --- | --- | --- |@@ -42,7 +42,7 @@ On every platform the app writes app-level state and logs on launch. The table b| `~/Library/Application Support/OpenKnowledge/path-install.json` | Records the `PATH`/shell changes it made and your `PATH`-consent choice, so they can be reverted | Outside-project (home dir) || `~/.ok/logs/desktop.<date>.log` | Desktop app + renderer log | Outside-project (home dir) || `~/.ok/mcp-status.json` | Records your first-launch MCP-setup consent choice | Outside-project (home dir) |-| `~/Library/Caches/OpenKnowledge-updater/` | Staged auto-update downloads (electron-updater) | Outside-project (home dir) |+| `~/Library/Caches/@inkeepopen-knowledge-desktop-updater/` | Staged auto-update downloads (electron-updater) | Outside-project (home dir) || `~/Library/Caches/com.inkeep.open-knowledge.ShipIt/` | Install log of the macOS update helper (Squirrel's ShipIt), which swaps the app bundle after the app has quit. The only record of why an update failed to install, so a bug report you send collects it — only this app's, never those of other applications that use the same update mechanism | Outside-project (home dir) || `~/Library/Application Support/OpenKnowledge/Crashpad/` | Native crash minidumps, written by the OS crash handler (Electron's Crashpad) if the app ever crashes. Local-only: the crash reporter runs with `uploadToServer: false`, so no dump is ever uploaded automatically | Outside-project (home dir) || `~/Library/Application Support/OpenKnowledge/bug-report-dirty-shutdown.json` | Dirty-shutdown sentinel — written on **every** launch, refreshed as it runs, and removed on a clean quit. The next launch reads it to tell an app crash (prompts you) from the machine ending the session — a reboot, an OS shutdown, or dying asleep (suppressed and logged instead) | Outside-project (home dir) |diff --git a/packages/cli/src/commands/editors.ts b/packages/cli/src/commands/editors.tsindex 966b06e92..56fde2aec 100644--- a/packages/cli/src/commands/editors.ts+++ b/packages/cli/src/commands/editors.ts@@ -620,7 +620,7 @@ export interface AppSupportOptions {env?: NodeJS.ProcessEnv;}-function pathApiForPlatform(platformName: NodeJS.Platform) {+export function pathApiForPlatform(platformName: NodeJS.Platform) {return platformName === 'win32' ? win32 : posix;}@@ -635,10 +635,10 @@ export function resolveAppSupportPath(options: AppSupportOptions = {}): string {}if (platformName === 'win32') {- return env.APPDATA ?? pathApi.join(home, 'AppData', 'Roaming');+ return env.APPDATA || pathApi.join(home, 'AppData', 'Roaming');}- return env.XDG_CONFIG_HOME ?? pathApi.join(home, '.config');+ return env.XDG_CONFIG_HOME || pathApi.join(home, '.config');}export function resolveClaudeCodeConfigPath(options: AppSupportOptions = {}): string {diff --git a/packages/cli/src/commands/removal-plan.test.ts b/packages/cli/src/commands/removal-plan.test.tsindex 917754b69..92a6310fb 100644--- a/packages/cli/src/commands/removal-plan.test.ts+++ b/packages/cli/src/commands/removal-plan.test.ts@@ -13,15 +13,18 @@ import { tmpdir } from 'node:os';import { dirname, join } from 'node:path';import { MCP_SERVER_NAME } from '@inkeep/open-knowledge-server';import { describe, expect, test } from 'vitest';+import { DESKTOP_UPDATER_CACHE_DIR_NAME } from '../integrations/desktop-state.ts';import { readPathInstallMarker } from '../integrations/path-shim.ts';import { buildManagedServerEntry } from './editors.ts';import {+ applicationDataOps,buildUninstallPlan,deinitOps,type RunRemovalDeps,runRemoval,type UninstallPlanInput,} from './removal-plan.ts';+import { formatRemovalPlan, removalPlanToJson } from './removal-render.ts';const OWN_ENTRY = buildManagedServerEntry({ mode: 'published' });@@ -58,7 +61,7 @@ function seedHome(home: string): void {join(home, 'Library', 'Application Support', 'Open Knowledge', 'state.json'),JSON.stringify({ theirData: true }),);- write(join(home, 'Library', 'Caches', 'OpenKnowledge-updater', 'pending.zip'), 'x');+ write(join(home, 'Library', 'Caches', DESKTOP_UPDATER_CACHE_DIR_NAME, 'pending.zip'), 'x');// Skill bundles (central + one host).write(join(home, '.agents', 'skills', 'open-knowledge-discovery', 'SKILL.md'), '# d\n');write(join(home, '.claude', 'skills', 'open-knowledge-discovery', 'SKILL.md'), '# d\n');@@ -143,7 +146,73 @@ describe('buildUninstallPlan ordering', () => {}});- test('on non-macOS the desktop-only surfaces (app data + PATH shim) are absent', () => {+ test.each([+ {+ platform: 'darwin' as const,+ home: '/Users/x',+ env: {},+ expected: [+ '/Users/x/Library/Application Support/OpenKnowledge',+ '/Users/x/Library/Application Support/Open Knowledge',+ `/Users/x/Library/Caches/${DESKTOP_UPDATER_CACHE_DIR_NAME}`,+ ],+ },+ {+ platform: 'win32' as const,+ home: 'C:\\Users\\x',+ env: {+ APPDATA: 'C:\\Users\\x\\AppData\\Roaming',+ LOCALAPPDATA: 'C:\\Users\\x\\AppData\\Local',+ },+ expected: [+ 'C:\\Users\\x\\AppData\\Roaming\\OpenKnowledge',+ `C:\\Users\\x\\AppData\\Local\\${DESKTOP_UPDATER_CACHE_DIR_NAME}`,+ ],+ },+ {+ platform: 'linux' as const,+ home: '/home/x',+ env: { XDG_CONFIG_HOME: '/xdg/config', XDG_CACHE_HOME: '/xdg/cache' },+ expected: ['/xdg/config/OpenKnowledge', `/xdg/cache/${DESKTOP_UPDATER_CACHE_DIR_NAME}`],+ },+ ])('plans only owned desktop data on $platform', ({ platform, home, env, expected }) => {+ const applicationData = applicationDataOps(home, platform, env);+ const paths = applicationData.map((op) => (op.kind === 'remove-path' ? op.path : null));++ expect(paths).toEqual(expected);+ expect(+ applicationData.filter((op) => op.kind === 'remove-path' && op.requireOurState),+ ).toHaveLength(platform === 'darwin' ? 1 : 0);+ });++ test('renders Linux desktop cleanup paths in human and JSON plans', () => {+ const plan = buildUninstallPlan({+ home: '/home/x',+ platform: 'linux',+ env: { XDG_CONFIG_HOME: '/home/x/.config', XDG_CACHE_HOME: '/home/x/.cache' },+ host: 'github.com',+ lockDirs: [],+ marker: null,+ recentDeinitProjectRoots: [],+ purgeContent: false,+ });++ const human = formatRemovalPlan(plan);+ expect(human).toContain('Application data:');+ expect(human).toContain('Remove ~/.config/OpenKnowledge');+ expect(human).toContain(`Remove ~/.cache/${DESKTOP_UPDATER_CACHE_DIR_NAME}`);++ const json = removalPlanToJson(plan);+ expect(json.mode).toBe('dry-run');+ expect(json.planned.map((item) => item.label)).toEqual(+ expect.arrayContaining([+ 'Remove ~/.config/OpenKnowledge',+ `Remove ~/.cache/${DESKTOP_UPDATER_CACHE_DIR_NAME}`,+ ]),+ );+ });++ test('keeps non-macOS PATH-shim behavior independent of desktop cleanup', () => {const home = mkdtempSync(join(tmpdir(), 'ok-uninst-'));try {const plan = buildUninstallPlan({@@ -152,16 +221,12 @@ describe('buildUninstallPlan ordering', () => {env: { XDG_CONFIG_HOME: join(home, '.config') },host: 'github.com',lockDirs: [],- marker: null, // no PATH shim on non-mac+ marker: null,recentDeinitProjectRoots: [],purgeContent: false,});- // Desktop-only surfaces driven by the `platform` param are absent: no- // application-data group (desktop is macOS-only) and no PATH-shim ops.- expect(plan.ops.some((o) => o.group === 'Application data')).toBe(false);+ expect(plan.ops.some((o) => o.group === 'Application data')).toBe(true);expect(plan.ops.some((o) => o.kind === 'shell-block')).toBe(false);- // The cross-platform surfaces (credentials, editor configs, skills, ~/.ok)- // remain, with ~/.ok last.expect(plan.ops.some((o) => o.kind === 'keychain-token')).toBe(true);expect(plan.ops.some((o) => o.group === 'Editor MCP configs')).toBe(true);expect(plan.ops.some((o) => o.group === 'Skill bundles')).toBe(true);@@ -361,7 +426,9 @@ describe('runRemoval — uninstall end to end', () => {// updater cache gone.expect(existsSync(join(home, 'Library', 'Application Support', 'OpenKnowledge'))).toBe(false);expect(existsSync(join(home, 'Library', 'Application Support', 'Open Knowledge'))).toBe(true);- expect(existsSync(join(home, 'Library', 'Caches', 'OpenKnowledge-updater'))).toBe(false);+ expect(existsSync(join(home, 'Library', 'Caches', DESKTOP_UPDATER_CACHE_DIR_NAME))).toBe(+ false,+ );// Skill bundles gone; a foreign skill in the shared store survives.expect(existsSync(join(home, '.agents', 'skills', 'open-knowledge-discovery'))).toBe(false);diff --git a/packages/cli/src/commands/removal-plan.ts b/packages/cli/src/commands/removal-plan.tsindex c2cc5d39f..e4ac7fba0 100644--- a/packages/cli/src/commands/removal-plan.ts+++ b/packages/cli/src/commands/removal-plan.ts@@ -31,6 +31,7 @@ import { clearAllEmbeddingsKeys } from '../auth/embeddings-key-store.ts';import { clearTokenFromAllBackends } from '../auth/token-store.ts';import {DESKTOP_LEGACY_PRODUCT_NAME,+ desktopUpdaterCacheDir,desktopUserDataDir,stateDirIsOurs,} from '../integrations/desktop-state.ts';@@ -328,8 +329,8 @@ export function buildUninstallPlan(input: UninstallPlanInput): RemovalPlan {});}- // 6. Application data (macOS desktop) — the current + identity-gated legacy- // userData dirs and the updater cache.+ // 6. Desktop application data — current userData + updater cache on every+ // supported platform, plus the identity-gated legacy userData on macOS.ops.push(...applicationDataOps(home, platform, input.env));// 7. Recent projects — each selected project runs the deinit ring.@@ -405,46 +406,46 @@ function pathRevertOps(marker: PathInstallMarker | null, home: string): RemovalOreturn ops;}-/**- * macOS desktop application-data dirs (current + identity-gated legacy userData,- * updater cache). Empty on non-macOS: OK Desktop is macOS-only, so the app-data- * surface is simply absent elsewhere (OK Desktop is macOS-only).- */-function applicationDataOps(+/** Desktop application-data dirs owned by OpenKnowledge. */+export function applicationDataOps(home: string,platform: NodeJS.Platform,env: NodeJS.ProcessEnv | undefined,): RemovalOp[] {- if (platform !== 'darwin') return [];const options = { home, platformName: platform, env };const current = desktopUserDataDir(options);- // The legacy dir name is generic ("Open Knowledge") — another vendor could own- // it — so it is ONLY removed when its state.json proves it is ours.- const legacy = desktopUserDataDir({ ...options, productName: DESKTOP_LEGACY_PRODUCT_NAME });- const updaterCache = join(home, 'Library', 'Caches', 'OpenKnowledge-updater');-- return [+ const updaterCache = desktopUpdaterCacheDir(options);+ const ops: RemovalOp[] = [{kind: 'remove-path',group: 'Application data',label: `Remove ${tildify(current, home)}`,path: current,},- {+ ];++ if (platform === 'darwin') {+ // The legacy dir name is generic ("Open Knowledge") — another vendor could+ // own it — so it is only removed when its state.json proves it is ours.+ const legacy = desktopUserDataDir({ ...options, productName: DESKTOP_LEGACY_PRODUCT_NAME });+ ops.push({kind: 'remove-path',group: 'Application data',label: `Remove ${tildify(legacy, home)} (only if it is OpenKnowledge's)`,path: legacy,requireOurState: true,- },- {- kind: 'remove-path',- group: 'Application data',- label: `Remove ${tildify(updaterCache, home)}`,- path: updaterCache,- },- ];+ });+ }++ ops.push({+ kind: 'remove-path',+ group: 'Application data',+ label: `Remove ${tildify(updaterCache, home)}`,+ path: updaterCache,+ });++ return ops;}// ---------------------------------------------------------------------------diff --git a/packages/cli/src/integrations/desktop-state.test.ts b/packages/cli/src/integrations/desktop-state.test.tsindex 695b8a773..0c9de776e 100644--- a/packages/cli/src/integrations/desktop-state.test.ts+++ b/packages/cli/src/integrations/desktop-state.test.ts@@ -1,10 +1,12 @@-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { describe, expect, test } from 'vitest';import {DESKTOP_LEGACY_PRODUCT_NAME,DESKTOP_PRODUCT_NAME,+ DESKTOP_UPDATER_CACHE_DIR_NAME,+ desktopUpdaterCacheDir,desktopUserDataDir,readDesktopRecentProjects,stateDirIsOurs,@@ -15,20 +17,32 @@ describe('desktopUserDataDir', () => {expect(desktopUserDataDir({ home: '/Users/x', platformName: 'darwin' })).toBe('/Users/x/Library/Application Support/OpenKnowledge',);+ expect(desktopUserDataDir({ home: '/home/x', platformName: 'linux', env: {} })).toBe(+ '/home/x/.config/OpenKnowledge',+ );+ expect(+ desktopUserDataDir({ home: '/home/x', platformName: 'linux', env: { XDG_CONFIG_HOME: '' } }),+ ).toBe('/home/x/.config/OpenKnowledge');expect(desktopUserDataDir({home: '/home/x',platformName: 'linux',- env: { XDG_CONFIG_HOME: '/home/x/.config' },+ env: { XDG_CONFIG_HOME: '/cfg' },}),- ).toBe('/home/x/.config/OpenKnowledge');+ ).toBe('/cfg/OpenKnowledge');expect(desktopUserDataDir({home: 'C:\\Users\\x',platformName: 'win32',env: { APPDATA: 'C:\\Users\\x\\AppData\\Roaming' },}),- ).toContain('OpenKnowledge');+ ).toBe('C:\\Users\\x\\AppData\\Roaming\\OpenKnowledge');+ expect(desktopUserDataDir({ home: 'C:\\Users\\x', platformName: 'win32', env: {} })).toBe(+ 'C:\\Users\\x\\AppData\\Roaming\\OpenKnowledge',+ );+ expect(+ desktopUserDataDir({ home: 'C:\\Users\\x', platformName: 'win32', env: { APPDATA: '' } }),+ ).toBe('C:\\Users\\x\\AppData\\Roaming\\OpenKnowledge');});test('the legacy product name resolves the space-named macOS dir', () => {@@ -44,6 +58,57 @@ describe('desktopUserDataDir', () => {});});+describe('desktopUpdaterCacheDir', () => {+ test('keeps the cache basename derived from the desktop package name', () => {+ const desktopPackage = JSON.parse(+ readFileSync(new URL('../../../desktop/package.json', import.meta.url), 'utf8'),+ ) as { name: string };+ const generatedName = `${desktopPackage.name.replace(/[/?<>\\:*|"]/g, '').toLowerCase()}-updater`;++ expect(DESKTOP_UPDATER_CACHE_DIR_NAME).toBe(generatedName);+ });++ test('matches electron-updater cache paths per platform', () => {+ expect(desktopUpdaterCacheDir({ home: '/Users/x', platformName: 'darwin', env: {} })).toBe(+ `/Users/x/Library/Caches/${DESKTOP_UPDATER_CACHE_DIR_NAME}`,+ );+ expect(desktopUpdaterCacheDir({ home: '/home/x', platformName: 'linux', env: {} })).toBe(+ `/home/x/.cache/${DESKTOP_UPDATER_CACHE_DIR_NAME}`,+ );+ expect(+ desktopUpdaterCacheDir({+ home: '/home/x',+ platformName: 'linux',+ env: { XDG_CACHE_HOME: '' },+ }),+ ).toBe(`/home/x/.cache/${DESKTOP_UPDATER_CACHE_DIR_NAME}`);+ expect(+ desktopUpdaterCacheDir({+ home: '/home/x',+ platformName: 'linux',+ env: { XDG_CACHE_HOME: '/cache' },+ }),+ ).toBe(`/cache/${DESKTOP_UPDATER_CACHE_DIR_NAME}`);+ expect(+ desktopUpdaterCacheDir({+ home: 'C:\\Users\\x',+ platformName: 'win32',+ env: { LOCALAPPDATA: 'D:\\Local' },+ }),+ ).toBe(`D:\\Local\\${DESKTOP_UPDATER_CACHE_DIR_NAME}`);+ expect(desktopUpdaterCacheDir({ home: 'C:\\Users\\x', platformName: 'win32', env: {} })).toBe(+ `C:\\Users\\x\\AppData\\Local\\${DESKTOP_UPDATER_CACHE_DIR_NAME}`,+ );+ expect(+ desktopUpdaterCacheDir({+ home: 'C:\\Users\\x',+ platformName: 'win32',+ env: { LOCALAPPDATA: '' },+ }),+ ).toBe(`C:\\Users\\x\\AppData\\Local\\${DESKTOP_UPDATER_CACHE_DIR_NAME}`);+ });+});+function writeState(dir: string, value: unknown): void {writeFileSync(join(dir, 'state.json'), JSON.stringify(value));}diff --git a/packages/cli/src/integrations/desktop-state.ts b/packages/cli/src/integrations/desktop-state.tsindex aa5e3fbf2..72bd154bd 100644--- a/packages/cli/src/integrations/desktop-state.ts+++ b/packages/cli/src/integrations/desktop-state.ts@@ -25,11 +25,22 @@*/import { existsSync, readFileSync } from 'node:fs';+import { homedir } from 'node:os';import { join } from 'node:path';-import { type AppSupportOptions, resolveAppSupportPath } from '../commands/editors.ts';+import {+ type AppSupportOptions,+ pathApiForPlatform,+ resolveAppSupportPath,+} from '../commands/editors.ts';/** Post-rename Electron `productName` — the userData basename on every platform. */export const DESKTOP_PRODUCT_NAME = 'OpenKnowledge';+/**+ * electron-builder derives this from the desktop package name+ * (`@inkeep/open-knowledge-desktop`). Keep this in lockstep with that package+ * name and electron-builder's `AppInfo.updaterCacheDirName` generation rule.+ */+export const DESKTOP_UPDATER_CACHE_DIR_NAME = '@inkeepopen-knowledge-desktop-updater';/** Pre-rename `productName` (macOS legacy `Open Knowledge`, with a space). A* generic name we don't own by name alone — always identity-gate before* deleting its dir. */@@ -46,8 +57,34 @@ interface DesktopUserDataOptions extends AppSupportOptions {* Windows %APPDATA%, Linux XDG config), matching Electron's own layout.*/export function desktopUserDataDir(options: DesktopUserDataOptions = {}): string {+ const platformName = options.platformName ?? process.platform;const productName = options.productName ?? DESKTOP_PRODUCT_NAME;- return join(resolveAppSupportPath(options), productName);+ return pathApiForPlatform(platformName).join(+ resolveAppSupportPath({ ...options, platformName }),+ productName,+ );+}++/**+ * Resolve electron-updater's cache directory using the same platform bases as+ * `AppAdapter.getAppCacheDir()` in the desktop runtime.+ */+export function desktopUpdaterCacheDir(options: AppSupportOptions = {}): string {+ const platformName = options.platformName ?? process.platform;+ const home = options.home ?? homedir();+ const env = options.env ?? process.env;+ const pathApi = pathApiForPlatform(platformName);++ let base: string;+ if (platformName === 'win32') {+ base = env.LOCALAPPDATA || pathApi.join(home, 'AppData', 'Local');+ } else if (platformName === 'darwin') {+ base = pathApi.join(home, 'Library', 'Caches');+ } else {+ base = env.XDG_CACHE_HOME || pathApi.join(home, '.cache');+ }++ return pathApi.join(base, DESKTOP_UPDATER_CACHE_DIR_NAME);}/** A recent project as the CLI needs it: the on-disk path + display name. */