@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/client/hooks/workspace/repo-scope/index.test.ts

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The repo pick is SHARED, not private per component or per panel.
+ *
+ * Every right-panel view that browses a repository keeps ONE selection
+ * (`workspace.activeRepo`), because they all describe the same working tree:
+ * picking in the file explorer must move the Source Control view and a
+ * terminal's cwd with it. A session that picked before the views shared a slot
+ * still has the value under its own panel's key, and must keep it.
+ *
+ * Rendered with `h()` (no JSX) against happy-dom. The persist path is driven
+ * through `flushSession` rather than the 600 ms debounce, so no timer is waited
+ * on.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import type { ComponentChild } from 'preact';
+import { act } from 'preact/test-utils';
+import { SessionStateProvider } from '@/client/components/common/session-state-provider/index';
+import { resolveRepoForPanel, useRepoScope } from '@/client/hooks/workspace/repo-scope';
+import { flushSession } from '@/shared/lib/workspace/session-state/store';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'HTMLInputElement', 'Event', 'MouseEvent', 'KeyboardEvent'] as const;
+/** The runner's own globals, restored on teardown — deleting them would strip natives (Event/CustomEvent) every later file needs. */const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+/** The runner's own fetch — this file replaces it for the whole process. */
+/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+const nativeFetch = Bun.fetch;
+
+const ROOT = '/ws';
+const OTHER_ROOT = '/other';
+const SESSION = 'new-repo-scope';
+
+let container: HTMLElement | undefined;
+let stored: Record<string, unknown> = {};
+const posted: Record<string, unknown>[] = [];
+
+/**
+ * Reads the shared slot at `rootPath`, and — when `repo` is given — owns a
+ * button that writes it, the way a panel's picker does.
+ */
+function Consumer({ id, rootPath, repo }: { id: string; rootPath: string; repo?: string }) {
+  const { activeRepo, setActiveRepo } = useRepoScope(rootPath);
+  return h(
+    'div',
+    { id },
+    h('span', null, activeRepo),
+    repo === undefined ? null : h('button', { onClick: () => setActiveRepo(repo) }, 'pick'),
+  );
+}
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in nativeGlobals)) nativeGlobals[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  target.fetch = async (_input: unknown, init?: { method?: string; body?: unknown }) => {
+    const json = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+    if (init?.method === 'POST') {
+      const body: unknown = JSON.parse(String(init.body));
+      // Test stub: the persist route takes `{ state: object }`.
+      if (body && typeof body === 'object' && 'state' in body && body.state && typeof body.state === 'object' && !Array.isArray(body.state)) {
+        posted.push(body.state as Record<string, unknown>);
+      }
+      return json({ success: true });
+    }
+    return json({ sessionId: SESSION, state: stored });
+  };
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (nativeGlobals[key] === undefined) delete target[key];
+    else target[key] = nativeGlobals[key];
+  }
+  // The runner's own fetch comes back: `delete` removed the global outright,
+  // so every suite after this one had no `fetch` at all.
+  target.fetch = nativeFetch;
+});
+
+afterEach(() => {
+  if (container) render(null, container);
+  container?.remove();
+  container = undefined;
+  stored = {};
+  posted.length = 0;
+});
+
+/** Mounts one session's consumers and drains the session-state load. */
+async function mount(children: ComponentChild, sessionId = SESSION): Promise<HTMLElement> {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(h(SessionStateProvider, { sessionId, children }), container as HTMLElement);
+  });
+  for (let i = 0; i < 20; i += 1) await act(async () => {});
+  if (!container) throw new Error('expected the mounted container');
+  return container;
+}
+
+const read = (id: string) => container?.querySelector(`#${id} span`)?.textContent;
+
+/** Clicks the picker button inside `#owner`'s consumer. */
+async function clickPicker() {
+  await act(async () => {
+    (container?.querySelector('#owner button') as HTMLButtonElement).click();
+  });
+}
+
+describe('useRepoScope', () => {
+  test('a write by one view reaches another view of the same workspace', async () => {
+    await mount(
+      h('div', null, h(Consumer, { id: 'owner', rootPath: ROOT, repo: 'projects/shared' }), h(Consumer, { id: 'follower', rootPath: ROOT })),
+    );
+    expect(read('follower')).toBe('.');
+
+    await clickPicker();
+
+    expect(read('owner')).toBe('projects/shared');
+    expect(read('follower')).toBe('projects/shared');
+  });
+
+  test('a pick made under another root does not name a directory of this one', async () => {
+    await mount(
+      h('div', null, h(Consumer, { id: 'owner', rootPath: ROOT, repo: 'projects/shared' }), h(Consumer, { id: 'elsewhere', rootPath: OTHER_ROOT })),
+    );
+
+    await clickPicker();
+
+    expect(read('owner')).toBe('projects/shared');
+    expect(read('elsewhere')).toBe('.');
+  });
+
+  test('adopts a pre-shared per-panel pick once, and leaves one key behind', async () => {
+    stored = {
+      'git.activeRepo': { root: ROOT, repo: 'projects/from-git' },
+      'files.activeRepo': { root: ROOT, repo: 'projects/from-files' },
+      'search.activeRepo': { root: OTHER_ROOT, repo: 'projects/elsewhere' },
+    };
+    const sessionId = 'new-repo-scope-legacy';
+
+    await mount(h(Consumer, { id: 'reader', rootPath: ROOT }), sessionId);
+    // The git panel's value wins: it is the pick the root-level fallback and the
+    // Source Control indicator were built around.
+    expect(read('reader')).toBe('projects/from-git');
+
+    await act(async () => {
+      await flushSession(sessionId);
+    });
+
+    const persisted = posted.at(-1);
+    expect(persisted?.['workspace.activeRepo']).toEqual({ root: ROOT, repo: 'projects/from-git' });
+    expect(persisted?.['git.activeRepo']).toBeUndefined();
+    expect(persisted?.['files.activeRepo']).toBeUndefined();
+    expect(persisted?.['search.activeRepo']).toBeUndefined();
+  });
+
+  test('adopts only a legacy pick that belongs to this root', async () => {
+    // The highest-priority legacy key names another workspace: the value that
+    // does belong here is the one to keep, and adopting the other would consume
+    // the one chance to migrate this session.
+    stored = {
+      'git.activeRepo': { root: OTHER_ROOT, repo: 'projects/elsewhere' },
+      'files.activeRepo': { root: ROOT, repo: 'projects/from-files' },
+    };
+    await mount(h(Consumer, { id: 'reader', rootPath: ROOT }), 'new-repo-scope-mixed');
+    expect(read('reader')).toBe('projects/from-files');
+
+    // Only values for another root: nothing to adopt, the root stays selected.
+    if (container) render(null, container);
+    stored = { 'git.activeRepo': { root: OTHER_ROOT, repo: 'projects/elsewhere' } };
+    await mount(h(Consumer, { id: 'reader', rootPath: ROOT }), 'new-repo-scope-stale');
+    expect(read('reader')).toBe('.');
+  });
+});
+
+describe('resolveRepoForPanel', () => {
+  test('keeps the pick when the workspace root is not a repo', () => {
+    // The user chose a nested repo; nothing about the root being a folder of
+    // repositories changes that.
+    expect(resolveRepoForPanel('projects/a', ['.', 'projects/a', 'projects/b'])).toBe('projects/a');
+    expect(resolveRepoForPanel('projects/a', ['projects/a', 'projects/b'])).toBe('projects/a');
+  });
+
+  test('keeps the root when the root IS a repo', () => {
+    // `.` is a real repository here, so it is a legitimate answer rather than
+    // "no pick" — falling through to a nested one would move the panel off the
+    // repo the user is looking at.
+    expect(resolveRepoForPanel('.', ['.', 'projects/a'])).toBe('.');
+  });
+
+  test('falls back to the FIRST repo, which is the sorted one', () => {
+    // No pick, and the root is not a repo: the fallback is the list's first
+    // entry. The list arrives sorted from the server (`getRepos`), which is what
+    // makes this deterministic — measured, `readdir` order differs between
+    // machines and after a directory is rewritten, so an unsorted list made the
+    // default repository differ between two reads of the same workspace.
+    expect(resolveRepoForPanel('.', ['alpha', 'conflicted'])).toBe('alpha');
+    expect(resolveRepoForPanel('.', ['conflicted', 'alpha'])).toBe('conflicted');
+  });
+
+  test('answers the root when there is nothing to fall back to', () => {
+    expect(resolveRepoForPanel('.', [])).toBe('.');
+  });
+});

package/src/client/hooks/workspace/repo-scope/index.ts

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Nested-repo scope for the right-panel views (files, search, git, terminal).
+ *
+ * Every one of them needs the same two things, and both are meaningless without
+ * the workspace root they describe:
+ *
+ *   - WHICH repo the view operates on (`useRepoScope`). A repo is a path
+ *     relative to the active root — `projects/jns6_5/token` only names a
+ *     directory under `~/JatisMobile/Workspace` — so a choice is only valid
+ *     next to the root it was made under.
+ *   - WHAT repos exist under that root (`useRepoList`), discovered server-side
+ *     and stored with the root it was discovered for (see `./store`).
+ *
+ * Kept as bare per-panel values, both outlived the workspace they belonged to:
+ * after a workspace switch the picker still listed the previous workspace's
+ * repos, still showed one of them as the selection, and every request the panel
+ * made named a path that did not exist under the new root. Pairing each value
+ * with its root invalidates it by construction — no reset effect to order
+ * against the per-session state restore — while a session returned to inside
+ * the same workspace keeps the repo it was left on.
+ *
+ * The choice is also ONE value for all four views (`REPO_SCOPE_STATE_KEY`), not
+ * one per panel: they describe the same working tree, so a repo picked in the
+ * file explorer has to move the search scope, the Source Control view and a
+ * terminal's cwd with it. Per-panel keys meant four pickers that could silently
+ * disagree about which repository was on screen.
+ */
+
+import { useCallback, useEffect, useRef, useSyncExternalStore } from 'preact/compat';
+import { useSessionStateContext } from '@/client/hooks/workspace/session-state/context';
+import { useSharedSessionState } from '@/client/hooks/workspace/session-state';
+import { clearSessionKey, getSessionValue } from '@/shared/lib/workspace/session-state/store';
+import { repoStore, UNKNOWN_LIST } from '@/client/hooks/workspace/repo-scope/store';
+
+/** A repo choice, kept next to the workspace root it was made under. */
+interface RepoPick {
+  root: string;
+  repo: string;
+}
+
+/**
+ * The one slot the selected repo lives in, shared by every right-panel view that
+ * browses a repository (files, search, git, terminal).
+ *
+ * One slot rather than one per panel: the views all describe the same working
+ * tree, so picking a repo in any of them must move the rest — otherwise the
+ * Files tree, the search scope, the Source Control view and a terminal's cwd can
+ * disagree about which repository they are showing, with nothing on screen
+ * saying why.
+ */
+export const REPO_SCOPE_STATE_KEY = 'workspace.activeRepo';
+
+/**
+ * Keys that held the pick before the views shared one selection, in the order a
+ * session carrying several is read. The git panel's value wins: that pick is the
+ * one the repo list's root-level fallback and the Source Control indicator were
+ * built around.
+ */
+const LEGACY_REPO_STATE_KEYS = ['git.activeRepo', 'files.activeRepo', 'search.activeRepo', 'terminal.activeRepo'];
+
+/**
+ * The repo a git panel works on: the user's pick, or — when they have none and
+ * the workspace root is not itself a repo — the first repo discovery found.
+ *
+ * The git loader applies the same fallback when it is sent no repo at all
+ * (`repo = repos.includes('.') ? '.' : repos[0]`), so resolving it here is what
+ * keeps the header label, the picker's checkmark and the requests all naming
+ * the repo git is actually operating on. Only git resolves it: browsing the
+ * workspace root is legitimate even when that root is not a repo — a folder of
+ * nested repos is a normal workspace — so the files, search and terminal panels
+ * keep `'.'` as the root itself.
+ */
+export function resolveRepoForPanel(pick: string, repos: readonly string[]): string {
+  if (pick !== '.' || repos.includes('.')) return pick;
+  return repos[0] ?? '.';
+}
+
+/**
+ * The repo the right panel works on, restored per session but dropped the moment
+ * the active workspace root changes.
+ *
+ * The pick is read SHARED (`useSharedSessionState`), not from a private copy:
+ * every view that shows a repo picker reads this one value, and a surface that
+ * only follows it — the activity bar's Source Control dot, the phone's tab bar —
+ * has no picker at all. A per-instance copy left those on the previous repo.
+ */
+export function useRepoScope(rootPath: string | undefined): {
+  activeRepo: string;
+  setActiveRepo: (repo: string) => void;
+  ready: boolean;
+} {
+  const { sessionId } = useSessionStateContext();
+  const [pick, setPick, ready] = useSharedSessionState<RepoPick | null>(REPO_SCOPE_STATE_KEY, null);
+  const scope = rootPath ?? '';
+
+  // Read through refs so the setter keeps ONE identity: it is handed to child
+  // components and used in effect dependencies, and `useSessionState` mints a
+  // fresh setter per render.
+  const scopeRef = useRef(scope);
+  scopeRef.current = scope;
+  const setPickRef = useRef(setPick);
+  setPickRef.current = setPick;
+  const setActiveRepo = useCallback((repo: string) => {
+    setPickRef.current({ root: scopeRef.current, repo });
+  }, []);
+
+  // A session that picked a repo while the panels kept their own keys still has
+  // it under its own panel's: adopt it, then leave one key behind. Clearing is
+  // unconditional — a legacy value that does not match this root names a
+  // directory the shared slot could not use anyway.
+  useEffect(() => {
+    if (!ready) return;
+    if (!pick) {
+      const adopted = LEGACY_REPO_STATE_KEYS
+        .map((key) => getSessionValue<RepoPick | null>(sessionId, key))
+        .find((candidate) => candidate && candidate.root === scope && candidate.repo);
+      if (adopted) setPickRef.current(adopted);
+    }
+    for (const key of LEGACY_REPO_STATE_KEYS) clearSessionKey(sessionId, key);
+  }, [ready, pick, scope, sessionId]);
+
+  // A pick made under another root (or stored before the root was recorded
+  // alongside it) names a directory that need not exist here: fall back to the
+  // workspace root.
+  const activeRepo =
+    pick && typeof pick === 'object' && pick.root === scope && typeof pick.repo === 'string' && pick.repo
+      ? pick.repo
+      : '.';
+
+  return { activeRepo, setActiveRepo, ready };
+}
+
+/**
+ * The repo a panel's picker resolves to right now, for the surfaces that follow
+ * the shared scope without owning a picker — the Source Control dot in the
+ * activity bar and the phone's tab bar. Same pick, same list, same fallback as
+ * the panel's own reads, so the dot describes the repository its view would show.
+ */
+export function useResolvedRepo(rootPath: string | undefined, active: boolean): string {
+  const { activeRepo } = useRepoScope(rootPath);
+  const { repos } = useRepoList(rootPath, active);
+  return resolveRepoForPanel(activeRepo, repos);
+}
+
+export interface RepoListHandle {
+  /** Repos of the active root; the workspace root alone until discovery answers. */
+  repos: string[];
+  /** Discovery is still running — the server said so, or a rescan is in flight. */
+  scanning: boolean;
+  /** Re-run discovery from scratch (the picker's refresh button). */
+  rescan: () => void;
+}
+
+/**
+ * Discovered repos of the active root.
+ *
+ * @param active - when false nothing is subscribed; a hidden panel has no use
+ *   for a list that costs the server a `find` over the workspace.
+ */
+export function useRepoList(rootPath: string | undefined, active: boolean): RepoListHandle {
+  const scope = rootPath ?? '';
+  const subscribe = useCallback(
+    (listener: () => void) => (active ? repoStore.subscribe(scope, listener) : () => {}),
+    [scope, active],
+  );
+  const getSnapshot = useCallback(
+    () => (active ? repoStore.snapshot(scope) : UNKNOWN_LIST),
+    [scope, active],
+  );
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot);
+  const rescan = useCallback(() => {
+    if (active) repoStore.rescan(scope);
+  }, [scope, active]);
+
+  return { repos: snapshot.repos, scanning: snapshot.scanning, rescan };
+}

package/src/client/hooks/workspace/repo-scope/store.test.ts

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Repo discovery now rides the `repos:<root>` realtime topic, so what this file
+ * pins is the store's own rules against a REAL socket: a new root never reports
+ * the previous root's list, one subscription per root is shared, a snapshot is
+ * adopted, a server republish (the background walk finishing) reaches the
+ * listener, and a rescan goes out over HTTP.
+ *
+ * Driven through a real server and socket rather than a stubbed fetch: the
+ * whole point of the change is that the walk's completion arrives as a frame,
+ * and a fake would only prove the fake's timing.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+
+import { createRepoStore, UNKNOWN_LIST } from '@/client/hooks/workspace/repo-scope/store';
+import { resetRealtimeClient } from '@/shared/lib/realtime/client';
+import { reposTopic } from '@/shared/lib/realtime/protocol';
+import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support/realtime-server';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+import type { TopicResolver } from '@/server/lib/realtime/hub.server';
+
+let server: RealtimeTestServer | undefined;
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+});
+
+afterEach(() => {
+  server?.stop();
+  server = undefined;
+  resetRealtimeClient();
+});
+
+/** A resolver table keyed by root, so each root answers its own list. */
+function resolversFor(byRoot: Map<string, { repos: string[]; reposPending?: boolean }>): Map<string, TopicResolver> {
+  const map = new Map<string, TopicResolver>();
+  for (const [root, payload] of byRoot) {
+    map.set(reposTopic(root), async () => payload);
+  }
+  return map;
+}
+
+/** A store whose rescan requests are recorded instead of sent. */
+function makeStore() {
+  const requests: string[] = [];
+  const store = createRepoStore({
+    fetch: async (url) => {
+      requests.push(url);
+      return { repos: ['.', 'projects/rescanned'], reposPending: false };
+    },
+  });
+  return { store, requests };
+}
+
+/** Let the socket's frames settle into the store. */
+async function drain(): Promise<void> {
+  for (let i = 0; i < 16; i += 1) await Promise.resolve();
+}
+
+describe('repo store over the repos topic', () => {
+  test('a snapshot is adopted, and a republish reaches the listener', async () => {
+    server = await startRealtimeTestServer(resolversFor(new Map([['/ws/a', { repos: ['.', 'projects/a'] }]])));
+    installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+    const { store } = makeStore();
+
+    const seen: string[][] = [];
+    const unsubscribe = store.subscribe('/ws/a', () => seen.push(store.snapshot('/ws/a').repos));
+    await server.waitForTopic(reposTopic('/ws/a'), (value) => value !== null);
+    await drain();
+
+    expect(store.snapshot('/ws/a').repos).toEqual(['.', 'projects/a']);
+
+    // The background walk finished: the server republishes the root's topic.
+    server.publish(reposTopic('/ws/a'), { repos: ['.', 'projects/a', 'projects/late'], reposPending: false });
+    await server.waitForTopic(reposTopic('/ws/a'), (value) => (value as { repos?: unknown[] })?.repos?.length === 3);
+    await drain();
+
+    expect(store.snapshot('/ws/a').repos).toEqual(['.', 'projects/a', 'projects/late']);
+    expect(seen).toContainEqual(['.', 'projects/a', 'projects/late']);
+    unsubscribe();
+  });
+
+  test('a new root never reports the previous root\'s repos', async () => {
+    server = await startRealtimeTestServer(resolversFor(new Map([
+      ['/ws/a', { repos: ['.', 'projects/a'] }],
+      ['/ws/b', { repos: ['.', 'projects/b'] }],
+    ])));
+    installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+    const { store } = makeStore();
+
+    const unsubscribeA = store.subscribe('/ws/a', () => {});
+    await server.waitForTopic(reposTopic('/ws/a'), (value) => value !== null);
+    await drain();
+    expect(store.snapshot('/ws/a').repos).toEqual(['.', 'projects/a']);
+
+    // Root B has no entry, so it starts from the root alone — not from A's list.
+    expect(store.snapshot('/ws/b')).toEqual(UNKNOWN_LIST);
+    unsubscribeA();
+
+    const unsubscribeB = store.subscribe('/ws/b', () => {});
+    await server.waitForTopic(reposTopic('/ws/b'), (value) => value !== null);
+    await drain();
+    expect(store.snapshot('/ws/b').repos).toEqual(['.', 'projects/b']);
+    // A's list was never published under B.
+    expect(store.snapshot('/ws/a').repos).toEqual(['.', 'projects/a']);
+    unsubscribeB();
+  });
+
+  test('a rescan asks the server over HTTP', async () => {
+    server = await startRealtimeTestServer(resolversFor(new Map([['/ws/a', { repos: ['.'] }]])));
+    installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+    const { store, requests } = makeStore();
+
+    const unsubscribe = store.subscribe('/ws/a', () => {});
+    await server.waitForTopic(reposTopic('/ws/a'), (value) => value !== null);
+    await drain();
+
+    store.rescan('/ws/a');
+    await store.settled('/ws/a');
+
+    expect(requests).toHaveLength(1);
+    expect(requests[0]).toContain('reposOnly=1');
+    expect(requests[0]).toContain('rescan=1');
+    expect(store.snapshot('/ws/a').repos).toEqual(['.', 'projects/rescanned']);
+    unsubscribe();
+  });
+
+  test('one topic subscription serves every listener of the same root', async () => {
+    let resolves = 0;
+    const resolvers = new Map<string, TopicResolver>([
+      [reposTopic('/ws/a'), async () => { resolves += 1; return { repos: ['.', 'projects/a'] }; }],
+    ]);
+    server = await startRealtimeTestServer(resolvers);
+    installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+    const { store } = makeStore();
+
+    const first = store.subscribe('/ws/a', () => {});
+    const second = store.subscribe('/ws/a', () => {});
+    await server.waitForTopic(reposTopic('/ws/a'), (value) => value !== null);
+    await drain();
+
+    // The topic resolved ONCE for two listeners: the store shares one
+    // subscription per root rather than one per panel.
+    expect(resolves).toBe(1);
+    first();
+    second();
+  });
+});