@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/fs/git-sync.test.ts

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Ahead/behind counts and the remote-ref refresh cache.
+ *
+ * The counts come from the LOCAL tracking ref, so they are only as fresh as
+ * the last fetch; the module's whole reason to exist is that nothing in the
+ * Kabmo ever fetched, leaving the Sync badge stuck at ↑0 ↓0 while origin had
+ * commits to pull. These tests build a real bare origin plus a clone in temp
+ * dirs and pin: the zero answer when there is no upstream, a local commit
+ * counting as ahead, a stale ref reporting zero until `refreshRemoteRefs`
+ * moves it, the TTL suppressing a repeat fetch, `invalidateRemoteRefs`
+ * forcing one, `markRemoteRefsFresh` suppressing the next one, and an
+ * unreachable remote degrading to the tracking ref instead of throwing.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import { testPosix } from '@/test-support/platform';
+import { removeDir } from '@/test-support/remove-dir';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  gitSyncCount,
+  invalidateRemoteRefs,
+  markRemoteRefsFresh,
+  refreshRemoteRefs,
+} from '@/server/lib/fs/git-sync';
+
+const tempDirs: string[] = [];
+
+function tempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-gitsync-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function git(cwd: string, ...args: string[]): string {
+  const result = Bun.spawnSync({ cmd: ['git', ...args], cwd });
+  if (result.exitCode !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${result.stderr.toString()}`);
+  }
+  return result.stdout.toString();
+}
+
+function initRepo(cwd: string): void {
+  git(cwd, 'init', '-q', '-b', 'main');
+  git(cwd, 'config', 'user.email', 'test@example.invalid');
+  git(cwd, 'config', 'user.name', 'Test');
+}
+
+function commitFile(cwd: string, name: string, message: string): void {
+  fs.writeFileSync(path.join(cwd, name), `${name}\n`);
+  git(cwd, 'add', '-A');
+  git(cwd, 'commit', '-q', '-m', message);
+}
+
+/** A bare origin plus a clone tracking it, each on its own temp path. */
+function makeClone(): { origin: string; clone: string } {
+  const origin = tempDir();
+  git(origin, 'init', '-q', '--bare', '-b', 'main');
+  const clone = tempDir();
+  git(tempDir(), 'clone', '-q', origin, clone);
+  initRepo(clone);
+  commitFile(clone, 'seed.txt', 'seed');
+  git(clone, 'push', '-q', '-u', 'origin', 'main');
+  return { origin, clone };
+}
+
+/** A second clone used only to move origin forward. */
+function pushToOrigin(origin: string, name: string): void {
+  const work = tempDir();
+  git(tempDir(), 'clone', '-q', origin, work);
+  initRepo(work);
+  commitFile(work, name, `remote ${name}`);
+  git(work, 'push', '-q');
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) removeDir(dir);
+});
+
+describe('gitSyncCount without an upstream', () => {
+  // A fresh local branch has no `@{upstream}`, and `git rev-list HEAD...@{upstream}`
+  // exits 128. Reporting `{ahead: 0}` there is the lie this pins: the badge read
+  // `↑0 ↓0` on a branch holding commits the next push would send.
+  test('a new local branch reports the commits a push would send', async () => {
+    const { clone } = makeClone();
+    git(clone, 'checkout', '-q', '-b', 'feat/x');
+    commitFile(clone, 'one.txt', 'one');
+    commitFile(clone, 'two.txt', 'two');
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 2, behind: 0 });
+  });
+
+  test('a repository with no remote at all reports its whole history as unpushed', async () => {
+    const repo = tempDir();
+    initRepo(repo);
+    commitFile(repo, 'a.txt', 'a');
+    expect(await gitSyncCount(repo)).toEqual({ ahead: 1, behind: 0 });
+  });
+
+  test('a branch whose commits are all published answers zero', async () => {
+    const { clone } = makeClone();
+    git(clone, 'checkout', '-q', '-b', 'feat/y');
+    commitFile(clone, 'y.txt', 'y');
+    git(clone, 'push', '-q', '-u', 'origin', 'feat/y');
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 0 });
+  });
+
+  test('a directory that is not a repository answers zero instead of throwing', async () => {
+    expect(await gitSyncCount(tempDir())).toEqual({ ahead: 0, behind: 0 });
+  });
+
+  test('refreshRemoteRefs is a no-op without an upstream', async () => {
+    // An empty repository has no `HEAD` to count, which is genuinely nothing to
+    // push — not the same case as a branch holding unpushed commits.
+    const repo = tempDir();
+    initRepo(repo);
+    await refreshRemoteRefs(repo);
+    expect(await gitSyncCount(repo)).toEqual({ ahead: 0, behind: 0 });
+  });
+});
+
+describe('ahead/behind against a real remote', () => {
+  test('a fresh clone is even with its origin', async () => {
+    const { clone } = makeClone();
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 0 });
+  });
+
+  test('a local commit counts as ahead without any fetch', async () => {
+    const { clone } = makeClone();
+    commitFile(clone, 'local.txt', 'local work');
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 1, behind: 0 });
+  });
+
+  testPosix('the stale tracking ref reports zero until a refresh moves it', async () => {
+    const { origin, clone } = makeClone();
+    pushToOrigin(origin, 'remote.txt');
+
+    // The ref has not moved: this is the badge that used to stay at zero.
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 0 });
+
+    await refreshRemoteRefs(clone);
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 1 });
+  });
+
+  // POSIX-only: these two push to a local `origin` and then wait on a fetch,
+  // and on Windows the push stalls until the 5s test timeout. The ahead/behind
+  // arithmetic itself is covered by the cases above, which need no network.
+  testPosix('a second refresh inside the TTL does not fetch again', async () => {
+    const { origin, clone } = makeClone();
+    await refreshRemoteRefs(clone);
+    pushToOrigin(origin, 'remote.txt');
+
+    await refreshRemoteRefs(clone);
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 0 });
+
+    // The forced refresh proves the ref really had moved and the TTL, not a
+    // failed fetch, is what kept the previous read at zero.
+    invalidateRemoteRefs(clone);
+    await refreshRemoteRefs(clone);
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 1 });
+  });
+
+  test('markRemoteRefsFresh suppresses the next fetch', async () => {
+    const { origin, clone } = makeClone();
+    invalidateRemoteRefs(clone);
+    markRemoteRefsFresh(clone);
+    pushToOrigin(origin, 'remote.txt');
+
+    await refreshRemoteRefs(clone);
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 0 });
+
+    invalidateRemoteRefs(clone);
+    await refreshRemoteRefs(clone);
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 1 });
+  });
+
+  test('an unreachable remote degrades to the tracking ref', async () => {
+    const { clone } = makeClone();
+    git(clone, 'remote', 'set-url', 'origin', path.join(tempDir(), 'no-such-remote.git'));
+
+    invalidateRemoteRefs(clone);
+    await refreshRemoteRefs(clone);
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 0, behind: 0 });
+  });
+
+  test('an unreachable remote still reports the local ahead count', async () => {
+    const { clone } = makeClone();
+    git(clone, 'remote', 'set-url', 'origin', path.join(tempDir(), 'no-such-remote.git'));
+    commitFile(clone, 'local.txt', 'local work');
+
+    invalidateRemoteRefs(clone);
+    await refreshRemoteRefs(clone);
+    expect(await gitSyncCount(clone)).toEqual({ ahead: 1, behind: 0 });
+  });
+});

package/src/server/lib/fs/git-sync.ts

@@ -0,0 +1,216 @@
+import { runShell, shellOk } from '@/server/lib/fs/shell';
+import { GIT_ENV } from '@/server/lib/fs/git-run';
+
+/**
+ * Ahead/behind counts behind the git panel's Sync button.
+ *
+ * `git rev-list --left-right --count HEAD...@{upstream}` counts against the
+ * LOCAL remote-tracking ref, and that ref only moves on fetch/pull/push.
+ * Nothing in Kabmo ever fetched, so `behind` reported the state of the
+ * last fetch rather than the remote: the badge sat at ↑0 ↓0 while origin had
+ * commits to pull, and the button — disabled by that very zero — could never
+ * correct itself.
+ *
+ * A read that asks for counts therefore refreshes the tracking ref first. The
+ * refresh is TTL'd so the git panel's 5s poll is not a 5s fetch loop, it is
+ * shared across the panels polling the same repo, and the loader starts it
+ * before its local git probes so the round trip overlaps instead of adding up.
+ */
+
+/** How long a fetch attempt — success or failure — is trusted. */
+const FETCH_TTL_MS = 60_000;
+/**
+ * How long a read waits for the fetch before answering from the tracking ref
+ * as it stands. A slow or offline remote must not stall the panel; the fetch
+ * keeps running under its own budget and a later read picks up the new ref.
+ */
+const FETCH_WAIT_MS = 3_000;
+/** Hard budget for one fetch; it is killed at the end of it. */
+const FETCH_TIMEOUT_MS = 15_000;
+
+export interface GitSyncCount {
+  ahead: number;
+  behind: number;
+}
+
+interface RemoteState {
+  /** When the last attempt settled; `0` means never attempted. */
+  at: number;
+  /** The running attempt, so concurrent reads share one fetch. */
+  inFlight: Promise<void> | null;
+}
+
+const remoteStates = new Map<string, RemoteState>();
+
+function stateFor(cwd: string): RemoteState {
+  let state = remoteStates.get(cwd);
+  if (!state) {
+    state = { at: 0, inFlight: null };
+    remoteStates.set(cwd, state);
+  }
+  return state;
+}
+
+/**
+ * Runs one `git fetch` with a hard deadline, returning whether it succeeded.
+ *
+ * Deliberately not `runShell`: that helper reads stdout and stderr to EOF, and
+ * a stalled fetch defeats it — git's own `git-remote-https` child survives the
+ * kill and keeps the inherited stderr pipe open, so the read never ends and the
+ * promise hangs forever. Verified on Bun 1.4.2: Bun's `timeout` closes stdout
+ * but not that inherited stderr, and the orphan lingers. Nothing here reads the
+ * fetch's output, so both streams are ignored (no pipe, nothing to hang on) and
+ * the process is killed by process group at the deadline — `detached` is what
+ * makes the group killable, and the group kill is what stops the helper from
+ * accumulating on every stalled attempt.
+ */
+async function runFetch(cwd: string, remote: string): Promise<boolean> {
+  const proc = Bun.spawn({
+    cmd: ['sh', '-c', `git fetch --quiet --no-tags '${remote.replace(/'/g, `'\\''`)}'`],
+    cwd,
+    stdin: 'ignore',
+    stdout: 'ignore',
+    stderr: 'ignore',
+    detached: true,
+    // Without this a remote that wants credentials blocks on stdin; the fetch
+    // then fails instead, and the counts fall back to the tracking ref.
+    env: { ...Bun.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, FETCH_TIMEOUT_MS);
+  });
+  const exitCode = await Promise.race([
+    proc.exited,
+    deadline.then(() => {
+      try {
+        process.kill(-proc.pid, 'SIGKILL');
+      } catch {
+        // Already gone, or the group could not be signalled: `exited` below
+        // still settles, and the ref simply stays as it was.
+      }
+      return proc.exited;
+    }),
+  ]);
+  clearTimeout(timer);
+  return exitCode === 0;
+}
+
+/**
+ * The branch's upstream remote, or null when it has none. Cheap and local, so
+ * the no-upstream case is never cached: configuring an upstream in the terminal
+ * shows up on the next read instead of up to a TTL later.
+ */
+async function readUpstreamRemote(cwd: string): Promise<string | null> {
+  try {
+    const result = await runShell('git rev-parse --abbrev-ref --symbolic-full-name @{upstream}', {
+      cwd,
+      timeout: 5_000,
+      env: GIT_ENV,
+    });
+    if (!shellOk(result)) return null;
+    const upstream = result.stdout.trim();
+    const slash = upstream.indexOf('/');
+    return slash > 0 ? upstream.slice(0, slash) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Refresh `cwd`'s remote-tracking refs, awaiting at most `FETCH_WAIT_MS`.
+ * Resolves immediately when the last attempt is still inside its TTL, and
+ * shares the running attempt when one is already in flight.
+ */
+export async function refreshRemoteRefs(cwd: string): Promise<void> {
+  const state = stateFor(cwd);
+  if (state.inFlight) return state.inFlight;
+  if (state.at !== 0 && Date.now() - state.at < FETCH_TTL_MS) return;
+
+  const remote = await readUpstreamRemote(cwd);
+  if (!remote) return;
+  // Reading the upstream is itself an await: another poll may have started the
+  // fetch, or completed one, in the meantime.
+  if (state.inFlight) return state.inFlight;
+  if (state.at !== 0 && Date.now() - state.at < FETCH_TTL_MS) return;
+
+  // The attempt never rejects — a failed fetch is not a broken panel — and
+  // always clears `inFlight` so a later read can retry.
+  state.inFlight = (async () => {
+    try {
+      await runFetch(cwd, remote);
+    } finally {
+      state.at = Date.now();
+      state.inFlight = null;
+    }
+  })();
+
+  // Bounded wait. `AbortSignal.timeout` rather than `Bun.sleep`: it is unref'd,
+  // so an abandoned wait cannot hold a live timer open on every read that
+  // refreshes.
+  const deadline = new Promise<void>((resolve) => {
+    AbortSignal.timeout(FETCH_WAIT_MS).addEventListener('abort', () => resolve(), { once: true });
+  });
+  await Promise.race([state.inFlight, deadline]);
+}
+
+/**
+ * Marks `cwd` as freshly fetched — a pull/push has already moved the tracking
+ * ref, so the next read must not fetch a state it just produced.
+ */
+export function markRemoteRefsFresh(cwd: string): void {
+  stateFor(cwd).at = Date.now();
+}
+
+/**
+ * Forces the next read to fetch. The counts are per-branch, so a checkout makes
+ * whatever the previous branch refreshed irrelevant.
+ */
+export function invalidateRemoteRefs(cwd: string): void {
+  stateFor(cwd).at = 0;
+}
+
+/**
+ * Ahead/behind against the branch's upstream, read from the local tracking ref
+ * (`refreshRemoteRefs` is what makes that ref current).
+ *
+ * A branch with **no upstream** — a fresh local branch, the common case right
+ * after "Create new branch" — has no `@{upstream}` to compare against, and
+ * `git rev-list HEAD...@{upstream}` exits 128. Reporting `{ahead: 0}` there is a
+ * lie that matters: the badge read `↑0 ↓0` on a branch holding unpushed commits
+ * and the Sync button (disabled by that zero, and by the tooltip it drives)
+ * could never correct itself. The unpushed commits are counted against the
+ * remote-tracking refs instead (`--not --remotes`), so `ahead` is the number of
+ * commits the next push would send. `behind` stays 0: without an upstream there
+ * is no ref to be behind, and the publish path sets one up.
+ *
+ * Both zero when git cannot answer at all (not a repository, git missing).
+ */
+export async function gitSyncCount(cwd: string): Promise<GitSyncCount> {
+  try {
+    // `git rev-list --left-right --count HEAD...@{upstream}` prints "<ahead>\t<behind>".
+    const result = await runShell('git rev-list --left-right --count HEAD...@{upstream}', {
+      cwd,
+      timeout: 8_000,
+      env: GIT_ENV,
+    });
+    if (shellOk(result)) {
+      const [ahead, behind] = result.stdout.trim().split(/\s+/).map(Number);
+      return { ahead: ahead || 0, behind: behind || 0 };
+    }
+
+    // No upstream (or a detached HEAD): count what a push would send. A
+    // repository with no remote at all answers its full history, which is what
+    // "nothing has been published" means — and is still the honest number.
+    const unpushed = await runShell('git rev-list --count HEAD --not --remotes', {
+      cwd,
+      timeout: 8_000,
+      env: GIT_ENV,
+    });
+    if (!shellOk(unpushed)) return { ahead: 0, behind: 0 };
+    return { ahead: Number(unpushed.stdout.trim()) || 0, behind: 0 };
+  } catch {
+    return { ahead: 0, behind: 0 };
+  }
+}

package/src/server/lib/fs/listing.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One directory's entries, as the file explorer renders them.
+ *
+ * Extracted from `routes/fs/read.ts` so the HTTP route and the realtime `fs:`
+ * topic produce the SAME listing — the ignored-path set, the folder-first sort
+ * and the unreadable-entry skip are exactly the details two copies would drift
+ * on, and a tree that disagrees with itself depending on which path delivered
+ * it is worse than either answer alone.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { collectIgnoredPaths } from '@/server/lib/fs/git-ignore';
+
+/** Directory names never listed: build output and VCS metadata. */
+const NOISE_DIRS: Record<string, true> = { node_modules: true, '.git': true, dist: true, build: true };
+
+export interface DirectoryEntry {
+  id: string;
+  name: string;
+  type: 'folder' | 'file';
+  path: string;
+  children?: null;
+  is_expanded?: number;
+  ignored: boolean;
+}
+
+/** Read one directory, folders first then files, each marked ignored or not. */
+export async function listDirectoryEntries(dirPath: string, rootPath: string): Promise<DirectoryEntry[]> {
+  const listed = (await fs.promises.readdir(dirPath))
+    .filter((child) => !NOISE_DIRS[child])
+    .map((child) => {
+      const full = path.join(dirPath, child);
+      return { child, full, rel: path.relative(rootPath, full) };
+    });
+
+  const ignored = await collectIgnoredPaths(rootPath, listed.map((entry) => entry.rel));
+
+  const mapped = await Promise.all(listed.map(async ({ child, full, rel }): Promise<DirectoryEntry | null> => {
+    try {
+      const st = await Bun.file(full).stat();
+      const isIgnored = ignored.has(rel);
+      if (st.isDirectory()) {
+        return { id: rel, name: child, type: 'folder', path: rel, children: null, is_expanded: 0, ignored: isIgnored };
+      }
+      return { id: rel, name: child, type: 'file', path: rel, ignored: isIgnored };
+    } catch {
+      return null; // unreadable entry / broken symlink — skip
+    }
+  }));
+
+  const result = mapped.filter((entry): entry is DirectoryEntry => entry !== null);
+  result.sort((a, b) => {
+    if (a.type === 'folder' && b.type === 'file') return -1;
+    if (a.type === 'file' && b.type === 'folder') return 1;
+    return a.name.localeCompare(b.name);
+  });
+  return result;
+}

package/src/server/lib/fs/package-root.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The package root resolvers, against the two layouts the running copy can be
+ * in — because the bug they exist to prevent is invisible in a checkout.
+ *
+ * The AOT bundle flattens every server module into `dist/client/index.js`, so a
+ * fixed `..` depth (the shape this replaced) resolves `dist/client` → four up →
+ * the GLOBAL INSTALL ROOT in a `bun add -g` install. That directory holds a
+ * `package.json` of its own, so nothing failed loudly: the update check read
+ * `version: undefined` and reported "no update", and the self-update classified
+ * the copy as unmanaged. Verified against a real published install before and
+ * after.
+ *
+ * The fixtures stage both layouts under a temp directory and pass the start
+ * directory explicitly, which is what makes the published shape reachable from
+ * inside the repo — the module's own `import.meta.dir` is always the checkout.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { packageDir, packageRoot } from '@/server/lib/fs/package-root';
+
+const created: string[] = [];
+
+function stage(layout: (root: string) => string): string {
+  const root = mkdtempSync(join(tmpdir(), 'kabmo-pkgroot-'));
+  created.push(root);
+  return layout(root);
+}
+
+afterEach(() => {
+  for (const dir of created.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+/** A published `bun add -g` install: the package under `node_modules/`, its deps in the parent. */
+function bunGlobal(startDir: string): string {
+  const global = join(startDir, 'install', 'global');
+  const pkg = join(global, 'node_modules', 'kabmo');
+  mkdirSync(join(pkg, 'dist', 'client'), { recursive: true });
+  mkdirSync(join(pkg, 'src', 'cli'), { recursive: true });
+  writeFileSync(join(pkg, 'package.json'), JSON.stringify({ name: 'kabmo', version: '4.3.0' }));
+  writeFileSync(join(pkg, 'src', 'cli', 'kabmo.js'), '#!/usr/bin/env bun\n');
+  mkdirSync(join(global, 'node_modules'), { recursive: true });
+  // The global install root carries its own package.json, which is what made the
+  // fixed-depth resolver read a version belonging to the wrong thing.
+  writeFileSync(join(global, 'package.json'), JSON.stringify({ dependencies: { kabmo: '4.3.0' } }));
+  return join(pkg, 'dist', 'client');
+}
+
+describe('packageDir', () => {
+  test('finds the package under a hoisted bun global install', () => {
+    const startDir = stage(bunGlobal);
+    const dir = packageDir(startDir, startDir);
+
+    expect(dir.endsWith(join('node_modules', 'kabmo'))).toBe(true);
+    expect(dir.endsWith(join('install', 'global'))).toBe(false);
+  });
+
+  test('finds the package in a source checkout, where src/ is beside the module', () => {
+    const startDir = stage((root) => {
+      mkdirSync(join(root, 'src', 'server', 'lib'), { recursive: true });
+      mkdirSync(join(root, 'node_modules'), { recursive: true });
+      return join(root, 'src', 'server', 'lib');
+    });
+
+    expect(packageDir(startDir, startDir)).toBe(join(startDir, '..', '..', '..'));
+  });
+
+  test('prefers the nearest root, so a nested install does not lose to an ancestor', () => {
+    const startDir = stage((root) => {
+      // An outer package root that would match first if the walk did not stop at
+      // the nearest one.
+      mkdirSync(join(root, 'src'), { recursive: true });
+      const inner = join(root, 'packages', 'kabmo');
+      mkdirSync(join(inner, 'src', 'server'), { recursive: true });
+      return join(inner, 'src', 'server');
+    });
+
+    expect(packageDir(startDir, startDir)).toBe(join(startDir, '..', '..'));
+  });
+});
+
+describe('packageRoot', () => {
+  test('answers the dependency root, which is the parent in a hoisted install', () => {
+    const startDir = stage(bunGlobal);
+    expect(packageRoot(startDir, startDir).endsWith(join('install', 'global'))).toBe(true);
+  });
+
+  test('falls back to the cwd when no root holds node_modules', () => {
+    const startDir = stage((root) => {
+      mkdirSync(join(root, 'empty'), { recursive: true });
+      return join(root, 'empty');
+    });
+
+    expect(packageRoot(startDir, startDir)).toBe(startDir);
+  });
+});

package/src/server/lib/fs/package-root.ts

@@ -0,0 +1,87 @@
+/**
+ * Where the running Kabmo package lives, and where its dependencies live.
+ *
+ * Two questions, deliberately separate, because the install shapes put them in
+ * different directories:
+ *
+ * - `packageRoot()` — the first directory that holds `node_modules`, i.e. where
+ *   the DEPENDENCIES are. A source checkout and a non-hoisted install answer
+ *   their own root; a hoisted install answers the PARENT of the package, since
+ *   a package under `node_modules/kabmo/` has no `node_modules` of its own.
+ * - `packageDir()` — the first directory that holds `src/`, i.e. where the
+ *   PACKAGE's own files are (`package.json`, `public/`, `dist/client/`, the
+ *   source stylesheets). In a hoisted install this is one level BELOW
+ *   `packageRoot()`.
+ *
+ * Both walk up from the running module rather than counting `..` segments. The
+ * bundle flattens every server module into `dist/client/index.js`, so a fixed
+ * depth is wrong the moment the layout differs from the one it was written for:
+ * four `..` from `dist/client` lands on `~/.bun/install/global`, a directory
+ * that holds a `package.json` belonging to the GLOBAL INSTALL ROOT — not to
+ * Kabmo. Reading the installed version there returned `null`, the update
+ * check reported no update, and the self-update classified the copy as
+ * "unmanaged" and refused to replace it. Walking up finds the real package in
+ * every layout instead.
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, join, parse, resolve } from 'node:path';
+
+/**
+ * Directories a package root may be found under, nearest first.
+ *
+ * `startDir` is the running module's directory — the repo root for the
+ * TypeScript entry, `dist/client` for the AOT bundle — and walking up from it
+ * finds both roots in every install shape. The cwd is included because a source
+ * checkout run from elsewhere still resolves its dependencies through it.
+ */
+export function searchRoots(startDir: string = import.meta.dir, cwd: string = process.cwd()): string[] {
+  const roots: string[] = [];
+  const seen = new Set<string>();
+  const add = (dir: string) => {
+    if (dir && !seen.has(dir)) {
+      seen.add(dir);
+      roots.push(dir);
+    }
+  };
+
+  let dir = startDir;
+  const { root } = parse(dir);
+  for (;;) {
+    add(dir);
+    if (dir === root) break;
+    dir = dirname(dir);
+  }
+  add(resolve(cwd));
+  return roots;
+}
+
+/**
+ * The package root — the first search root that holds `node_modules`.
+ *
+ * Falling back to the cwd keeps a checkout with no `node_modules` (a publish
+ * dry-run) working.
+ */
+export function packageRoot(startDir: string = import.meta.dir, cwd: string = process.cwd()): string {
+  for (const root of searchRoots(startDir, cwd)) {
+    // `existsSync` rather than `Bun.file().exists()`: the latter is async and
+    // file-only, and `node_modules` is a directory.
+    if (existsSync(join(root, 'node_modules'))) return root;
+  }
+  return cwd;
+}
+
+/**
+ * The package's own directory — the first search root that holds `src/`.
+ *
+ * This is the directory holding the running copy's `package.json`, so it is
+ * what the self-update reads the installed version from and what the restart
+ * helper runs the CLI out of. Resolving either through `packageRoot()` would
+ * name the parent in a hoisted install, where neither exists.
+ */
+export function packageDir(startDir: string = import.meta.dir, cwd: string = process.cwd()): string {
+  for (const root of searchRoots(startDir, cwd)) {
+    if (existsSync(join(root, 'src'))) return root;
+  }
+  return packageRoot(startDir, cwd);
+}