Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.mdx
index 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.ts
index 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.ts
index 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.ts
index 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): RemovalO
return 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.ts
index 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.ts
index 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. */