Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(desktop): silence no-op "Installed CLI shims." startup toast (#2240)

mike-inkeep89978b86aee6
diff --git a/.changeset/silent-noop-cli-shim-toast.md b/.changeset/silent-noop-cli-shim-toast.md
new file mode 100644
index 000000000..c130a4088
--- /dev/null
+++ b/.changeset/silent-noop-cli-shim-toast.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Desktop: stop showing the sticky "Installed CLI shims." startup toast when an app upgrade only repoints the internal `~/.ok/bin` symlinks. The startup PATH-reclaim toast now fires only for changes the user can see or act on — a shell rc-file edit, an opt-out, a legacy-symlink cleanup, or a failure. A no-op symlink repoint (the common case on every upgrade or bundle-path change) is now silent; the repoint still happens and still emits the structured `path-install-symlink-success` event for operators. Restores the spec's "silent if no meaningful user-facing change" contract.
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index daa21aea2..db85ff3bf 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -183,7 +183,7 @@ import {
recordFirstRunShareHandoff,
recordOnboardingFlow,
} from './onboarding-telemetry.ts';
-import { type EnsureCliOnPathResult, ensureCliOnPath } from './path-install.ts';
+import { computePathLeg, type EnsureCliOnPathResult, ensureCliOnPath } from './path-install.ts';
import { installStdioBrokenPipeGuard } from './process-safety-net.ts';
import {
checkAndRepairProjectMcpOnProjectOpen,
@@ -1434,12 +1434,7 @@ function dispatchStartupReclaimToastWhenReady(results: {
path: EnsureCliOnPathResult;
}): void {
const { mcp, path } = results;
- const pathLeg =
- path.status === 'installed'
- ? ({ status: 'installed', summary: path.summary } as const)
- : path.status === 'failed-all'
- ? ({ status: 'failed', summary: path.error } as const)
- : ({ status: 'none' } as const);
+ const pathLeg = computePathLeg(path);
if (mcp.status === 'failed') {
dispatchToastWhenReady({
kind: 'startup-reclaim',
diff --git a/packages/desktop/src/main/path-install.test.ts b/packages/desktop/src/main/path-install.test.ts
index 5d7515eac..97ee46ebd 100644
--- a/packages/desktop/src/main/path-install.test.ts
+++ b/packages/desktop/src/main/path-install.test.ts
@@ -11,7 +11,12 @@ import {
} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
-import { ensureCliOnPath, pathInstallMarkerPath } from './path-install.ts';
+import {
+ computePathLeg,
+ type EnsureCliOnPathResult,
+ ensureCliOnPath,
+ pathInstallMarkerPath,
+} from './path-install.ts';
const EXE = '/Applications/OpenKnowledge.app/Contents/MacOS/OpenKnowledge';
const WRAPPER = '/Applications/OpenKnowledge.app/Contents/Resources/cli/bin/ok.sh';
@@ -33,6 +38,7 @@ describe('ensureCliOnPath', () => {
spawn: async () => ({ code: 0, stdout: `${h}/.ok/bin:/usr/bin`, stderr: '' }),
});
expect(result.status).toBe('installed');
+ if (result.status === 'installed') expect(result.summary).toContain('~/.zshrc');
expect(readlinkSync(join(h, '.ok', 'bin', 'ok'))).toBe(WRAPPER);
expect(readlinkSync(join(h, '.ok', 'bin', 'open-knowledge'))).toBe(WRAPPER);
expect(readFileSync(join(h, '.ok', 'env.sh'), 'utf8')).toContain(
@@ -77,7 +83,7 @@ describe('ensureCliOnPath', () => {
env: { HOME: h, SHELL: '/bin/zsh' },
spawn: async () => ({ code: 0, stdout: `${h}/.ok/bin`, stderr: '' }),
});
- expect(repaired.status).toBe('installed');
+ expect(repaired.status).toBe('installed-silent');
expect(readlinkSync(join(h, '.ok', 'bin', 'ok'))).toBe(WRAPPER);
});
@@ -177,6 +183,7 @@ describe('ensureCliOnPath', () => {
logger: { event: (e) => events.push(e) },
});
expect(result.status).toBe('installed');
+ if (result.status === 'installed') expect(result.summary).toContain('leftover ok symlink');
expect(() => lstatSync(join(bin, 'ok'))).toThrow();
expect(readlinkSync(join(bin, 'open-knowledge'))).toBe('/elsewhere/ok.sh');
const marker = JSON.parse(readFileSync(markerPath, 'utf8'));
@@ -280,8 +287,35 @@ describe('ensureCliOnPath', () => {
const newWrapper =
'/Users/someone/Applications/OpenKnowledge.app/Contents/Resources/cli/bin/ok.sh';
const result = await ensureCliOnPath(opts(newExe));
- expect(result.status).toBe('installed');
+ expect(result.status).toBe('installed-silent');
expect(readlinkSync(join(h, '.ok', 'bin', 'ok'))).toBe(newWrapper);
expect(readlinkSync(join(h, '.ok', 'bin', 'open-knowledge'))).toBe(newWrapper);
});
});
+
+describe('computePathLeg', () => {
+ const marker = {} as Extract<EnsureCliOnPathResult, { status: 'installed' }>['marker'];
+
+ test('installed → installed leg with its summary (the only success that toasts)', () => {
+ expect(computePathLeg({ status: 'installed', marker, summary: 'Added ok to PATH.' })).toEqual({
+ status: 'installed',
+ summary: 'Added ok to PATH.',
+ });
+ });
+
+ test('installed-silent → none (symlink-only repoint stays silent)', () => {
+ expect(computePathLeg({ status: 'installed-silent', marker })).toEqual({ status: 'none' });
+ });
+
+ test('failed-all → failed leg carrying the error', () => {
+ expect(computePathLeg({ status: 'failed-all', error: 'EACCES' })).toEqual({
+ status: 'failed',
+ summary: 'EACCES',
+ });
+ });
+
+ test('skipped / healthy-current → none', () => {
+ expect(computePathLeg({ status: 'skipped', reason: 'platform' })).toEqual({ status: 'none' });
+ expect(computePathLeg({ status: 'healthy-current', marker })).toEqual({ status: 'none' });
+ });
+});
diff --git a/packages/desktop/src/main/path-install.ts b/packages/desktop/src/main/path-install.ts
index 5ef5d62e7..57b89e3f6 100644
--- a/packages/desktop/src/main/path-install.ts
+++ b/packages/desktop/src/main/path-install.ts
@@ -82,8 +82,35 @@ export type EnsureCliOnPathResult =
| { status: 'skipped'; reason: string }
| { status: 'healthy-current'; marker: PathInstallMarker }
| { status: 'installed'; marker: PathInstallMarker; summary: string }
+ | { status: 'installed-silent'; marker: PathInstallMarker }
| { status: 'failed-all'; error: string };
+/** The PATH leg of the combined startup-reclaim toast (consumed by the main
+ * process dispatcher + serialized to the renderer). `none` = stay silent. */
+export type StartupToastPathLeg =
+ | { status: 'none' }
+ | { status: 'installed'; summary: string }
+ | { status: 'failed'; summary: string };
+
+export function computePathLeg(result: EnsureCliOnPathResult): StartupToastPathLeg {
+ switch (result.status) {
+ case 'installed':
+ return { status: 'installed', summary: result.summary };
+ case 'failed-all':
+ return { status: 'failed', summary: result.error };
+ case 'installed-silent':
+ case 'healthy-current':
+ case 'skipped':
+ return { status: 'none' };
+ default: {
+ const _exhaustive: never = result;
+ throw new Error(
+ `unhandled ensureCliOnPath status: ${(_exhaustive as { status: string }).status}`,
+ );
+ }
+ }
+}
+
interface EnsureCliOnPathOpts {
executablePath: string;
isPackaged: boolean;
@@ -482,11 +509,8 @@ export async function ensureCliOnPath(opts: EnsureCliOnPathOpts): Promise<Ensure
parts.push(
`Removed ${cleanup.removedCount} leftover ok symlink(s) created by an older version.`,
);
- return {
- status: 'installed',
- marker,
- summary: parts.length > 0 ? parts.join(' ') : 'Installed CLI shims.',
- };
+ if (parts.length === 0) return { status: 'installed-silent', marker };
+ return { status: 'installed', marker, summary: parts.join(' ') };
} catch (err) {
const error = err instanceof Error ? err.message : String(err);
const stack = err instanceof Error ? err.stack : undefined;