Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): branch-aware locate-locally share-receive (#1865)

miles-kt-inkeepbc34222b6524
diff --git a/.changeset/share-receive-local-locate-branch-aware.md b/.changeset/share-receive-local-locate-branch-aware.md
new file mode 100644
index 000000000..bea8f6f03
--- /dev/null
+++ b/.changeset/share-receive-local-locate-branch-aware.md
@@ -0,0 +1,18 @@
+---
+"@inkeep/open-knowledge-desktop": patch
+"@inkeep/open-knowledge-app": patch
+---
+
+fix(open-knowledge): branch-aware "I already have it locally" share-receive
+
+Opening a share link for a branch you don't have checked out, for a repo that
+isn't in your recent projects, now shows the branch-switch dialog when you
+locate the repo via "I already have it locally" — the same prompt you already
+get when the shared repo is in your recent projects. Previously this path opened
+the project on whatever branch happened to be checked out and silently showed
+the wrong (or an empty) document; the branch-switch choice only appeared on a
+second click, once locating the repo had added it to your recent projects. The
+receive flow now reads the located clone's current branch and, on a mismatch
+with the share's branch, routes to the branch-switch surface (open on the
+current branch vs switch to the shared branch) instead of opening on the wrong
+branch.
diff --git a/packages/app/src/components/ShareReceiveDialog.dom.test.tsx b/packages/app/src/components/ShareReceiveDialog.dom.test.tsx
index 138dd832d..e7e6e8489 100644
--- a/packages/app/src/components/ShareReceiveDialog.dom.test.tsx
+++ b/packages/app/src/components/ShareReceiveDialog.dom.test.tsx
@@ -383,13 +383,190 @@ describe('ShareReceiveDialog runtime behavior', () => {
'This folder is a clone of fork/repo, not inkeep/open-knowledge. Pick a different folder?',
),
);
- await waitFor(() =>
- expect(bridge.project.open).toHaveBeenCalledWith({
- entryPoint: 'share-receive',
- path: '/right',
- pendingDeepLinkTarget: { kind: 'doc', path: 'docs/guide.md' },
- target: 'new-window',
- }),
+ await waitFor(() => expect(bridge.project.readHeadBranch).toHaveBeenCalledWith('/right'));
+ await waitFor(() => {
+ const openArg = (bridge.project.open as ReturnType<typeof mock>).mock.calls.at(-1)?.[0] as {
+ path?: string;
+ pendingDeepLinkTarget?: unknown;
+ pendingShareBranchSwitch?: { projectPath?: string; currentBranch?: string | null };
+ };
+ expect(openArg.path).toBe('/right');
+ expect(openArg.pendingShareBranchSwitch?.currentBranch).toBe('main');
+ expect(openArg.pendingDeepLinkTarget).toBeUndefined();
+ });
+ });
+
+ test('I have it locally: branch mismatch routes to the branch-switch surface, not a plain open', async () => {
+ const bridge = createBridge();
+ const store = createTestStore(okPayload({ branch: 'feat/share' }));
+ bridge.__folderPicks.push('/local/clone');
+ bridge.__validationResults.push({
+ kind: 'ok',
+ gitRemoteUrl: 'https://github.com/inkeep/open-knowledge.git',
+ });
+
+ await renderDialog({ bridge, store });
+
+ expect(await screen.findByTestId('share-receive-dialog')).toBeTruthy();
+ fireEvent.click(screen.getByTestId('share-receive-local'));
+
+ await waitFor(() => expect(bridge.project.readHeadBranch).toHaveBeenCalledWith('/local/clone'));
+
+ await waitFor(() => expect(bridge.project.open).toHaveBeenCalled());
+ const openArg = (bridge.project.open as ReturnType<typeof mock>).mock.calls.at(-1)?.[0] as {
+ path?: string;
+ pendingDeepLinkTarget?: unknown;
+ pendingShareBranchSwitch?: {
+ projectPath?: string;
+ currentBranch?: string | null;
+ share?: { owner?: string; repo?: string; branch?: string; target?: unknown };
+ };
+ };
+ expect(openArg.path).toBe('/local/clone');
+ expect(openArg.pendingShareBranchSwitch).toBeDefined();
+ expect(openArg.pendingShareBranchSwitch?.projectPath).toBe('/local/clone');
+ expect(openArg.pendingShareBranchSwitch?.currentBranch).toBe('main');
+ expect(openArg.pendingShareBranchSwitch?.share).toMatchObject({
+ owner: 'inkeep',
+ repo: 'open-knowledge',
+ branch: 'feat/share',
+ target: { kind: 'doc', docPath: 'docs/guide.md' },
+ });
+ expect(openArg.pendingDeepLinkTarget).toBeUndefined();
+ expect(store.dismiss).toHaveBeenCalled();
+ });
+
+ test('I have it locally: branch match opens directly without a branch-switch', async () => {
+ const bridge = createBridge();
+ const store = createTestStore(okPayload({ branch: 'main' }));
+ bridge.__folderPicks.push('/local/clone');
+ bridge.__validationResults.push({
+ kind: 'ok',
+ gitRemoteUrl: 'https://github.com/inkeep/open-knowledge.git',
+ });
+
+ await renderDialog({ bridge, store });
+
+ expect(await screen.findByTestId('share-receive-dialog')).toBeTruthy();
+ fireEvent.click(screen.getByTestId('share-receive-local'));
+
+ await waitFor(() => expect(bridge.project.open).toHaveBeenCalled());
+ const openArg = (bridge.project.open as ReturnType<typeof mock>).mock.calls.at(-1)?.[0] as {
+ pendingDeepLinkTarget?: unknown;
+ pendingShareBranchSwitch?: unknown;
+ };
+ expect(openArg.pendingDeepLinkTarget).toEqual({ kind: 'doc', path: 'docs/guide.md' });
+ expect(openArg.pendingShareBranchSwitch).toBeUndefined();
+ expect(store.dismiss).toHaveBeenCalled();
+ });
+
+ test('I have it locally: detached HEAD with a share branch routes to the branch-switch surface', async () => {
+ const bridge = createBridge();
+ const store = createTestStore(okPayload({ branch: 'feat/share' }));
+ bridge.__folderPicks.push('/local/clone');
+ bridge.__validationResults.push({
+ kind: 'ok',
+ gitRemoteUrl: 'https://github.com/inkeep/open-knowledge.git',
+ });
+ bridge.project.readHeadBranch = mock(() =>
+ Promise.resolve({ currentBranch: null, detached: true, headSha: '1234567' }),
+ );
+
+ await renderDialog({ bridge, store });
+
+ expect(await screen.findByTestId('share-receive-dialog')).toBeTruthy();
+ fireEvent.click(screen.getByTestId('share-receive-local'));
+
+ await waitFor(() => expect(bridge.project.open).toHaveBeenCalled());
+ const openArg = (bridge.project.open as ReturnType<typeof mock>).mock.calls.at(-1)?.[0] as {
+ pendingDeepLinkTarget?: unknown;
+ pendingShareBranchSwitch?: {
+ currentBranch?: string | null;
+ share?: { branch?: string; target?: unknown };
+ };
+ };
+ expect(openArg.pendingShareBranchSwitch).toBeDefined();
+ expect(openArg.pendingShareBranchSwitch?.currentBranch).toBeNull();
+ expect(openArg.pendingShareBranchSwitch?.share).toMatchObject({
+ branch: 'feat/share',
+ target: { kind: 'doc', docPath: 'docs/guide.md' },
+ });
+ expect(openArg.pendingDeepLinkTarget).toBeUndefined();
+ });
+
+ test('I have it locally: unreadable HEAD (all-null sentinel) opens directly, no needless switch', async () => {
+ const bridge = createBridge();
+ const store = createTestStore(okPayload({ branch: 'feat/share' }));
+ bridge.__folderPicks.push('/local/clone');
+ bridge.__validationResults.push({
+ kind: 'ok',
+ gitRemoteUrl: 'https://github.com/inkeep/open-knowledge.git',
+ });
+ bridge.project.readHeadBranch = mock(() =>
+ Promise.resolve({ currentBranch: null, detached: false, headSha: null }),
);
+
+ await renderDialog({ bridge, store });
+
+ expect(await screen.findByTestId('share-receive-dialog')).toBeTruthy();
+ fireEvent.click(screen.getByTestId('share-receive-local'));
+
+ await waitFor(() => expect(bridge.project.open).toHaveBeenCalled());
+ const openArg = (bridge.project.open as ReturnType<typeof mock>).mock.calls.at(-1)?.[0] as {
+ pendingDeepLinkTarget?: unknown;
+ pendingShareBranchSwitch?: unknown;
+ };
+ expect(openArg.pendingDeepLinkTarget).toEqual({ kind: 'doc', path: 'docs/guide.md' });
+ expect(openArg.pendingShareBranchSwitch).toBeUndefined();
+ expect(store.dismiss).toHaveBeenCalled();
+ });
+
+ test('I have it locally: share with no branch opens directly', async () => {
+ const bridge = createBridge();
+ const store = createTestStore(okPayload({ branch: '' }));
+ bridge.__folderPicks.push('/local/clone');
+ bridge.__validationResults.push({
+ kind: 'ok',
+ gitRemoteUrl: 'https://github.com/inkeep/open-knowledge.git',
+ });
+
+ await renderDialog({ bridge, store });
+
+ expect(await screen.findByTestId('share-receive-dialog')).toBeTruthy();
+ fireEvent.click(screen.getByTestId('share-receive-local'));
+
+ await waitFor(() => expect(bridge.project.open).toHaveBeenCalled());
+ const openArg = (bridge.project.open as ReturnType<typeof mock>).mock.calls.at(-1)?.[0] as {
+ pendingDeepLinkTarget?: unknown;
+ pendingShareBranchSwitch?: unknown;
+ };
+ expect(openArg.pendingDeepLinkTarget).toEqual({ kind: 'doc', path: 'docs/guide.md' });
+ expect(openArg.pendingShareBranchSwitch).toBeUndefined();
+ expect(store.dismiss).toHaveBeenCalled();
+ });
+
+ test('I have it locally: readHeadBranch IPC rejection falls back to a plain open', async () => {
+ const bridge = createBridge();
+ const store = createTestStore(okPayload({ branch: 'feat/share' }));
+ bridge.__folderPicks.push('/local/clone');
+ bridge.__validationResults.push({
+ kind: 'ok',
+ gitRemoteUrl: 'https://github.com/inkeep/open-knowledge.git',
+ });
+ bridge.project.readHeadBranch = mock(() => Promise.reject(new Error('ipc channel closed')));
+
+ await renderDialog({ bridge, store });
+
+ expect(await screen.findByTestId('share-receive-dialog')).toBeTruthy();
+ fireEvent.click(screen.getByTestId('share-receive-local'));
+
+ await waitFor(() => expect(bridge.project.open).toHaveBeenCalled());
+ const openArg = (bridge.project.open as ReturnType<typeof mock>).mock.calls.at(-1)?.[0] as {
+ pendingDeepLinkTarget?: unknown;
+ pendingShareBranchSwitch?: unknown;
+ };
+ expect(openArg.pendingDeepLinkTarget).toEqual({ kind: 'doc', path: 'docs/guide.md' });
+ expect(openArg.pendingShareBranchSwitch).toBeUndefined();
+ expect(store.dismiss).toHaveBeenCalled();
});
});
diff --git a/packages/app/src/components/ShareReceiveDialog.tsx b/packages/app/src/components/ShareReceiveDialog.tsx
index 302623e87..e29620d98 100644
--- a/packages/app/src/components/ShareReceiveDialog.tsx
+++ b/packages/app/src/components/ShareReceiveDialog.tsx
@@ -1,5 +1,6 @@
// biome-ignore-all lint/plugin/no-raw-html-interactive-element: pre-rule backlog — Q2 card grid uses raw <button> awaiting shadcn migration; tracked at https://github.com/inkeep/open-knowledge/blob/main/biome-plugins/README.md#no-raw-html-interactive-elementgrit
+import { classifyBranchMatch } from '@inkeep/open-knowledge-core';
import { Trans, useLingui } from '@lingui/react/macro';
import { Loader2 } from 'lucide-react';
import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
@@ -17,6 +18,7 @@ import {
DialogTitle,
} from '@/components/ui/dialog';
import {
+ type HeadBranchInfo,
type OkDesktopBridge,
type OkLocalOpAuthStatusResponse,
type OkShareReceivedPayload,
@@ -272,15 +274,36 @@ function ShareReceiveDialogInner({
});
console.log(formatReceiveLog({ folder_validate: result.kind }));
if (result.kind === 'ok') {
+ const shareBranch = launcherMiss.share.branch;
+ let head: HeadBranchInfo = { currentBranch: null, headSha: null, detached: false };
+ try {
+ head = await bridge.project.readHeadBranch(folderPath);
+ } catch (err) {
+ console.warn(
+ '[receive] local-folder readHeadBranch failed',
+ err instanceof Error ? err.message : err,
+ );
+ }
+ const needsBranchSwitch = classifyBranchMatch(shareBranch, head) !== 'true';
try {
await bridge.project.open({
path: folderPath,
target: 'new-window',
entryPoint: 'share-receive',
- pendingDeepLinkTarget: {
- kind: launcherMiss.share.target.kind,
- path: shareTargetPath(launcherMiss.share.target),
- },
+ ...(needsBranchSwitch
+ ? {
+ pendingShareBranchSwitch: {
+ share: launcherMiss.share,
+ projectPath: folderPath,
+ currentBranch: head.currentBranch,
+ },
+ }
+ : {
+ pendingDeepLinkTarget: {
+ kind: launcherMiss.share.target.kind,
+ path: shareTargetPath(launcherMiss.share.target),
+ },
+ }),
});
store.dismiss();
} catch (err) {
diff --git a/packages/app/src/lib/desktop-bridge-types.ts b/packages/app/src/lib/desktop-bridge-types.ts
index f1bf37140..335c44bde 100644
--- a/packages/app/src/lib/desktop-bridge-types.ts
+++ b/packages/app/src/lib/desktop-bridge-types.ts
@@ -524,6 +524,11 @@ export interface OkDesktopBridge {
entryPoint: OkProjectEntryPoint;
pendingDeepLinkTarget?: { kind: 'doc' | 'folder'; path: string };
pendingBranch?: string | null;
+ pendingShareBranchSwitch?: {
+ share: OkSharePayloadFields;
+ projectPath: string;
+ currentBranch: string | null;
+ };
}): Promise<void>;
createNew(args: {
parent: string;
diff --git a/packages/core/src/desktop-bridge.ts b/packages/core/src/desktop-bridge.ts
index b99fce97e..dc5b22573 100644
--- a/packages/core/src/desktop-bridge.ts
+++ b/packages/core/src/desktop-bridge.ts
@@ -67,6 +67,11 @@ interface OkProjectOpenRequest {
entryPoint: OkProjectEntryPoint;
pendingDeepLinkTarget?: { kind: 'doc' | 'folder'; path: string };
pendingBranch?: string | null;
+ pendingShareBranchSwitch?: {
+ share: OkSharePayloadFields;
+ projectPath: string;
+ currentBranch: string | null;
+ };
}
export type OkCheckTargetExistsResult = 'exists' | 'missing' | 'unreadable';
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index df99c17f9..df7edd71f 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -1867,12 +1867,27 @@ function registerIpcHandlers() {
return undefined;
}
}
+ if (request.pendingShareBranchSwitch !== undefined && wm) {
+ const existing = wm.focusWindowForProject(request.path) as
+ | (BrowserWindowLike & { webContents: BrowserWindowLike['webContents'] })
+ | null;
+ if (existing) {
+ sendToRenderer(existing.webContents, 'ok:share:received', {
+ kind: 'project-branch-switch' as const,
+ share: request.pendingShareBranchSwitch.share,
+ projectPath: request.pendingShareBranchSwitch.projectPath,
+ currentBranch: request.pendingShareBranchSwitch.currentBranch,
+ });
+ return undefined;
+ }
+ }
await openProjectOrFallbackToNavigator(
request.path,
request.entryPoint,
request.pendingDeepLinkTarget,
request.pendingBranch,
request.pendingMultiCandidate,
+ request.pendingShareBranchSwitch,
);
return undefined;
});
diff --git a/packages/desktop/src/shared/bridge-contract.ts b/packages/desktop/src/shared/bridge-contract.ts
index fc72303ea..c91804b63 100644
--- a/packages/desktop/src/shared/bridge-contract.ts
+++ b/packages/desktop/src/shared/bridge-contract.ts
@@ -508,6 +508,11 @@ export interface OkDesktopBridge {
entryPoint: EntryPoint;
pendingDeepLinkTarget?: { kind: 'doc' | 'folder'; path: string };
pendingBranch?: string | null;
+ pendingShareBranchSwitch?: {
+ share: OkSharePayloadFields;
+ projectPath: string;
+ currentBranch: string | null;
+ };
}): Promise<void>;
createNew(args: {
parent: string;
diff --git a/packages/desktop/src/shared/ipc-channels.ts b/packages/desktop/src/shared/ipc-channels.ts
index bdf9cb09d..3e89dccaf 100644
--- a/packages/desktop/src/shared/ipc-channels.ts
+++ b/packages/desktop/src/shared/ipc-channels.ts
@@ -21,6 +21,7 @@ import type {
OkLocalOpAuthReposResponse,
OkLocalOpAuthStatusResponse,
OkServerRestartOutcome,
+ OkSharePayloadFields,
OkThemeSource,
OkUpdateChannel,
SeedApplyOptions,
@@ -67,6 +68,11 @@ interface ProjectOpenRequest {
entryPoint: EntryPoint;
pendingDeepLinkTarget?: { kind: 'doc' | 'folder'; path: string };
pendingBranch?: string | null;
+ pendingShareBranchSwitch?: {
+ share: OkSharePayloadFields;
+ projectPath: string;
+ currentBranch: string | null;
+ };
pendingMultiCandidate?: boolean;
}