@kabmo-labs/kabmo 0.0.1 → 0.2.0

package/src/client/lib/native/back.test.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+
+import {
+  BACK_PROPERTY,
+  dispatchBack,
+  installBackDispatcher,
+  registerBackHandler,
+} from '@/client/lib/native/back';
+
+/**
+ * The stack is module state, so every case unregisters what it added. The
+ * shell's contract is exactly two facts: last-registered wins, and the first
+ * handler that answers `true` stops the walk.
+ */
+const cleanups: Array<() => void> = [];
+
+function onBack(handler: () => boolean): () => boolean {
+  const remove = registerBackHandler(handler);
+  cleanups.push(remove);
+  return handler;
+}
+
+afterEach(() => {
+  while (cleanups.length > 0) cleanups.pop()!();
+});
+
+describe('dispatchBack', () => {
+  test('reports false when nothing is registered', () => {
+    expect(dispatchBack()).toBe(false);
+  });
+
+  test('the last registered handler runs first', () => {
+    const order: string[] = [];
+    onBack(() => {
+      order.push('first');
+      return false;
+    });
+    onBack(() => {
+      order.push('second');
+      return true;
+    });
+
+    expect(dispatchBack()).toBe(true);
+    expect(order).toEqual(['second']);
+  });
+
+  test('the first true stops the walk', () => {
+    const order: string[] = [];
+    onBack(() => {
+      order.push('inner');
+      return true;
+    });
+    onBack(() => {
+      order.push('outer');
+      return false;
+    });
+
+    expect(dispatchBack()).toBe(true);
+    expect(order).toEqual(['outer', 'inner']);
+  });
+
+  test('a throwing handler is skipped, and the next one still gets the press', () => {
+    onBack(() => {
+      throw new Error('broken handler');
+    });
+    onBack(() => true);
+
+    expect(dispatchBack()).toBe(true);
+  });
+
+  test('unregistering removes the handler', () => {
+    let calls = 0;
+    const remove = registerBackHandler(() => {
+      calls += 1;
+      return false;
+    });
+    remove();
+
+    expect(dispatchBack()).toBe(false);
+    expect(calls).toBe(0);
+  });
+});
+
+describe('installBackDispatcher', () => {
+  test('exposes window.__kabmoBack and is idempotent', () => {
+    const win = new Window({ url: 'http://localhost/' });
+    const target = globalThis as unknown as Record<string, unknown>;
+    const previous = target.window;
+    target.window = win;
+    try {
+      installBackDispatcher();
+      installBackDispatcher();
+
+      const installed = (win as unknown as Record<string, unknown>)[BACK_PROPERTY];
+      expect(typeof installed).toBe('function');
+      expect((installed as () => boolean)()).toBe(false);
+    } finally {
+      target.window = previous;
+      win.close();
+    }
+  });
+});

package/src/client/lib/native/back.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Android hardware back button, delegated to the page.
+ *
+ * The shell asks `window.__kabmoBack()` before it walks WebView history, and
+ * that indirection exists because of a real mismatch: Kabmo's phone layout keeps
+ * its screens in React state (`MobileLayoutWrapper`'s `currentScreen`), not in
+ * the URL. `history.back()` therefore reopens a previous session while leaving
+ * the drawer that opened it on screen — the user presses back and the app
+ * appears to do something unrelated.
+ *
+ * Handlers are a STACK, last-registered first: a settings dialog mounted over the
+ * layout gets the press before the layout does, which is the order the user sees.
+ * Each handler answers whether it consumed the press; the first `true` wins.
+ */
+
+export type BackHandler = () => boolean;
+
+/** The property the shell calls. Named once so both sides agree. */
+export const BACK_PROPERTY = '__kabmoBack';
+
+const handlers: BackHandler[] = [];
+
+/** Register a handler; the returned function removes it. */
+export function registerBackHandler(handler: BackHandler): () => void {
+  handlers.push(handler);
+  return () => {
+    const index = handlers.indexOf(handler);
+    if (index >= 0) handlers.splice(index, 1);
+  };
+}
+
+/**
+ * Ask the page to consume a back press.
+ *
+ * Exported for tests and for a caller that wants the same precedence without the
+ * native shell (a keyboard shortcut). Reverse order is the whole contract, and a
+ * throwing handler is skipped rather than allowed to strand the user in a screen
+ * they cannot leave.
+ */
+export function dispatchBack(): boolean {
+  for (let index = handlers.length - 1; index >= 0; index -= 1) {
+    try {
+      if (handlers[index]()) return true;
+    } catch {
+      // Fall through to the next handler; history is the final fallback.
+    }
+  }
+  return false;
+}
+
+/** Install `window.__kabmoBack`. Idempotent — a hot reload re-runs it. */
+export function installBackDispatcher(): void {
+  if (typeof window === 'undefined') return;
+  (window as unknown as Record<string, unknown>)[BACK_PROPERTY] = dispatchBack;
+}

package/src/client/main.tsx

@@ -8,6 +8,7 @@ import { installAuthFetchBridge, primeAuthState } from '@/client/hooks/ui/auth';
 import { installPluginRuntime } from '@/client/lib/plugins/runtime';
 import { installUiKit } from '@/client/lib/plugins/kit';
 import { installScrollbarActivity } from '@/client/lib/scrollbar-activity';
+import { installBackDispatcher } from '@/client/lib/native/back';
 import { installFileLaunchHandler } from '@/client/lib/launch/file-handlers';
 
 import '@/client/tailwind.css';
@@ -53,6 +54,11 @@ installUiKit();
 // already covered.
 installScrollbarActivity();
 
+// The native shell asks `window.__kabmoBack()` before walking WebView history.
+// Installed before the first render for the same reason the listener above is:
+// a back press during hydration must find the dispatcher, not `undefined`.
+installBackDispatcher();
+
 // A file the OS handed to Kabmo (PWA File Handling) arrives as a
 // `FileSystemFileHandle` on `launchQueue`, and the consumer must be installed
 // before the first render: launches that happened before the script ran are

package/src/client/tailwind.css

@@ -43,6 +43,12 @@
      of the K's upper arm (`public/icon.svg`) — and it is the only chroma
      outside the error red. */
   --color-brand: #f26522;
+  /* The icon's tile and the ink on it, also not theme tokens: the wordmark's K
+     is the app icon (`public/icon.svg`), so its green plate and cream strokes
+     must be identical in every palette — including the dark ones, where a
+     themed surface would turn the plate into a hole. */
+  --color-brand-tile: #0b5d3b;
+  --color-brand-cream: #f7f4ea;
 }
 
 @layer base {

package/src/server/lib/fs/git-actions-branch.ts

@@ -102,8 +102,25 @@ export const GIT_BRANCH_ACTIONS: Record<string, GitActionHandler> = {
   },
 
   async sync({ targetDir }) {
+    // A merge/rebase already stopped on a conflict is a state the operation
+    // bar owns: a pull there is refused by git ("You have not concluded your
+    // merge"), and letting that refusal through would report the conflict as
+    // a failed sync. Naming it points the user at the bar instead.
+    const before = await readGitState(targetDir);
+    if (before.operation) {
+      throw new Error(
+        `Finish the ${OPERATION_LABELS[before.operation]} first — Sync is unavailable while an operation is in progress.`,
+      );
+    }
     await pullBranch(targetDir);
-    await pushBranch(targetDir);
+    // A pull that stopped on a conflict has nothing to push yet: the merge is
+    // unresolved, so `git push` refuses ("Updates were rejected because the
+    // remote contains work…") and the route would report a failed Sync over a
+    // conflict the panel is about to offer to resolve. The operation bar is
+    // the surface that has to be reached, so the push is skipped and the
+    // working tree is left exactly as the pull left it.
+    const after = await readGitState(targetDir);
+    if (!after.operation) await pushBranch(targetDir);
     // Both commands already moved the tracking ref; the next read must not
     // fetch again to see a state it just produced.
     markRemoteRefsFresh(targetDir);

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

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `sync` ACTION, not just the pull under it.
+ *
+ * `pullBranch` is pinned by `git-publish.test.ts`; what is pinned here is the
+ * handler's own two rules, both invisible from the pull alone:
+ *
+ * - A pull that stops on a conflict SKIPS the push. `git push` refuses while
+ *   the merge is unresolved, so without the skip the route answered 400 over a
+ *   conflict the operation bar was about to offer to resolve — the reported
+ *   "Sync failed" on the exact state the panel has a surface for.
+ * - A tree already in an operation is refused BY NAME rather than by git's
+ *   "You have not concluded your merge" — the panel can only act on an
+ *   operation it knows about, and an error that names it is what points the
+ *   user at the bar.
+ *
+ * Driven against real repositories: the exit codes, the merge commit and the
+ * `MERGE_HEAD` file are the whole subject.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { GIT_BRANCH_ACTIONS } from '@/server/lib/fs/git-actions-branch';
+import { removeDir } from '@/test-support/remove-dir';
+
+const tempDirs: string[] = [];
+
+function tempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-gitsync-action-'));
+  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, content?: string): void {
+  fs.writeFileSync(path.join(cwd, name), content ?? `${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 };
+}
+
+/** Commit `name` in a second clone of `origin` and push it. */
+function pushFromOtherClone(origin: string, name: string, message: string, content?: string): void {
+  const other = tempDir();
+  git(tempDir(), 'clone', '-q', origin, other);
+  initRepo(other);
+  commitFile(other, name, message, content);
+  git(other, 'push', '-q');
+}
+
+function counts(cwd: string): string {
+  return git(cwd, 'rev-list', '--count', '--left-right', 'HEAD...@{upstream}').trim();
+}
+
+/** One sync, through the same handler the route dispatches. */
+async function sync(cwd: string): Promise<void> {
+  const handler = GIT_BRANCH_ACTIONS.sync;
+  await handler({ formData: new FormData(), targetDir: cwd });
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) removeDir(dir);
+});
+
+describe('the sync action', () => {
+  test('reconciles a diverged branch and publishes the result', async () => {
+    const { origin, clone } = makeClone();
+    pushFromOtherClone(origin, 'other.txt', 'other');
+    commitFile(clone, 'mine.txt', 'mine');
+    git(clone, 'fetch', '-q');
+    expect(counts(clone)).toBe('1\t1');
+
+    await sync(clone);
+
+    // Both sides landed and the remote has them: nothing ahead or behind.
+    expect(counts(clone)).toBe('0\t0');
+    expect(fs.existsSync(path.join(clone, 'other.txt'))).toBe(true);
+    expect(git(clone, 'log', '-1', '--pretty=%s')).toContain('Merge branch');
+  });
+
+  test('leaves a conflicted merge open and does not push over it', async () => {
+    const { origin, clone } = makeClone();
+    commitFile(clone, 'seed.txt', 'mine', 'mine\n');
+    pushFromOtherClone(origin, 'seed.txt', 'theirs', 'theirs\n');
+    git(clone, 'fetch', '-q');
+
+    // The pull exits 1 with MERGE_HEAD in place; the handler must treat that as
+    // the state to show, not as a failure.
+    await sync(clone);
+
+    expect(fs.existsSync(path.join(clone, '.git', 'MERGE_HEAD'))).toBe(true);
+    expect(git(clone, 'status', '--porcelain=v1')).toContain('UU seed.txt');
+  });
+
+  test('refuses by name while an operation is already in progress', async () => {
+    const { origin, clone } = makeClone();
+    commitFile(clone, 'seed.txt', 'mine', 'mine\n');
+    pushFromOtherClone(origin, 'seed.txt', 'theirs', 'theirs\n');
+    git(clone, 'fetch', '-q');
+    // Start the merge the way the panel does, then try to sync over it.
+    Bun.spawnSync({ cmd: ['git', 'merge', '--no-edit', '--', '@{upstream}'], cwd: clone });
+    expect(fs.existsSync(path.join(clone, '.git', 'MERGE_HEAD'))).toBe(true);
+
+    // `expect(...).rejects` is typed as returning void by Bun's matcher types,
+    // so awaiting it is a no-op — the explicit catch is what actually waits.
+    let refusal = '';
+    try {
+      await sync(clone);
+    } catch (error) {
+      refusal = error instanceof Error ? error.message : String(error);
+    }
+    expect(refusal).toMatch(/finish the merge first/i);
+  });
+});

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

@@ -13,6 +13,10 @@
  * refusal, not a failure — and treating it as an error aborted Sync before it
  * ever reached the push. Driven against real repositories, because the exit
  * codes and the `-u` upstream write are what the module exists for.
+ *
+ * The pull suite also pins the DIVERGED case, where `--ff-only` exits 128 and
+ * Sync silently did nothing (one local commit, one on origin) — see the merge
+ * test and `pullBranch`'s own comment.
  */
 
 import { afterAll, describe, expect, test } from 'bun:test';
@@ -66,6 +70,32 @@ function upstreamOf(cwd: string): string {
   return git(cwd, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').trim();
 }
 
+/** "<ahead>\t<behind>" against the upstream — `1\t1` is a diverged branch. */
+function counts(cwd: string): string {
+  return git(cwd, 'rev-list', '--count', '--left-right', 'HEAD...@{upstream}').trim();
+}
+
+/**
+ * A second clone of `origin` that commits `name` and pushes it, so the branch
+ * under test is behind by one — the other half of a divergence.
+ *
+ * `content` overrides what the file holds, which is what makes the two sides
+ * CONFLICT instead of one of them being an unrelated new path.
+ */
+function pushFromOtherClone(origin: string, name: string, message: string, content?: string): void {
+  const other = tempDir();
+  git(tempDir(), 'clone', '-q', origin, other);
+  initRepo(other);
+  if (content === undefined) {
+    commitFile(other, name, message);
+  } else {
+    fs.writeFileSync(path.join(other, name), content);
+    git(other, 'add', '-A');
+    git(other, 'commit', '-q', '-m', message);
+  }
+  git(other, 'push', '-q');
+}
+
 afterAll(() => {
   for (const dir of tempDirs) removeDir(dir);
 });
@@ -144,4 +174,70 @@ describe('pullBranch', () => {
 
     expect(fs.existsSync(path.join(clone, 'remote.txt'))).toBe(true);
   });
+
+  /**
+   * The reported Sync failure: one local commit and one on origin.
+   *
+   * `--ff-only` exits 128 here ("Not possible to fast-forward, aborting."), so
+   * Sync threw before the push and the badge stayed at ↑1 ↓1 with git's advice
+   * text on screen. The fix is the merge pull, and the assertion is the state
+   * after a REAL push: nothing left ahead or behind.
+   */
+  test('merges a diverged branch instead of refusing, and the push then lands', async () => {
+    const { origin, clone } = makeClone();
+    pushFromOtherClone(origin, 'other.txt', 'other');
+    commitFile(clone, 'mine.txt', 'mine');
+    git(clone, 'fetch', '-q');
+    expect(counts(clone)).toBe('1\t1');
+
+    await pullBranch(clone);
+    await pushBranch(clone);
+
+    expect(counts(clone)).toBe('0\t0');
+    // The merge commit carries the remote branch's name, which is what a pull
+    // writes — not a rebase, whose history would hold two linear commits.
+    expect(git(clone, 'log', '-1', '--pretty=%s')).toContain('Merge branch');
+    expect(fs.existsSync(path.join(clone, 'other.txt'))).toBe(true);
+  });
+
+  /**
+   * A pull that stops on a conflict exits 1 with `MERGE_HEAD` in place — the
+   * state the operation bar exists to show, not a failed sync. Throwing there
+   * reported the conflict as an error and never reached the panel's own
+   * "resolve the conflicts" surface.
+   */
+  test('accepts a pull that stops on a conflict, leaving the merge open', async () => {
+    const { origin, clone } = makeClone();
+    // `seed.txt` exists on both sides already, so the two edits CONFLICT —
+    // a file only one side has would merge cleanly (`AA` only when both
+    // created it, which is a different shape than a content conflict).
+    fs.writeFileSync(path.join(clone, 'seed.txt'), 'mine\n');
+    git(clone, 'commit', '-q', '-am', 'mine');
+    pushFromOtherClone(origin, 'seed.txt', 'theirs', 'theirs\n');
+    git(clone, 'fetch', '-q');
+
+    await pullBranch(clone);
+
+    expect(fs.existsSync(path.join(clone, '.git', 'MERGE_HEAD'))).toBe(true);
+    expect(git(clone, 'status', '--porcelain=v1')).toContain('UU seed.txt');
+  });
+
+  /**
+   * The pull is pinned to merge semantics whatever the repository's own
+   * `pull.ff`/`pull.rebase` say — a Sync button must not mean two things.
+   */
+  test('does not inherit pull.ff=only, which reproduces the refusal', async () => {
+    const { origin, clone } = makeClone();
+    pushFromOtherClone(origin, 'other.txt', 'other');
+    commitFile(clone, 'mine.txt', 'mine');
+    git(clone, 'fetch', '-q');
+    git(clone, 'config', 'pull.ff', 'only');
+
+    await pullBranch(clone);
+
+    // Ahead by the local commit plus the merge commit, and no longer behind:
+    // the pull brought origin in rather than refusing it.
+    expect(counts(clone)).toBe('2\t0');
+    expect(git(clone, 'log', '-1', '--pretty=%s')).toContain('Merge branch');
+  });
 });

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

@@ -13,7 +13,7 @@
  *    branch" when the branch was never published, so Sync failed outright on
  *    exactly the branch whose commits it was supposed to send. `push -u <remote>
  *    HEAD` sets the upstream while it publishes.
- *  - `git pull --ff-only` exits 1 with "There is no tracking information for the
+ *  - `git pull` exits 1 with "There is no tracking information for the
  *    current branch" for the same branch — a refusal, not a failure of the
  *    user's intent: there is nothing to pull yet. Treating it as an error
  *    aborted Sync before it reached the push.
@@ -23,6 +23,7 @@
  */
 
 import { runGit, type GitRunResult } from '@/server/lib/fs/git-run';
+import { readGitState } from '@/server/lib/fs/git-state';
 
 /** Runs a git command and throws with its stderr when it exits non-zero. */
 async function expectOk(args: string[], cwd: string, timeout?: number): Promise<GitRunResult> {
@@ -62,12 +63,43 @@ export async function pushBranch(cwd: string): Promise<void> {
 }
 
 /**
- * Pull with fast-forward only, standing down on a branch with no upstream.
+ * Pull the branch's upstream, standing down on a branch with no upstream.
  *
  * Nothing to pull is not an error, and aborting here is what stopped Sync from
  * ever publishing a fresh branch.
+ *
+ * **`--ff-only` was wrong, and it is the reported "Sync does nothing when I
+ * have one local commit and one on origin".** On a DIVERGED branch git refuses
+ * it outright — measured: `fatal: Not possible to fast-forward, aborting.`
+ * (exit 128) — so Sync threw before it reached the push, the badge stayed at
+ * `↑1 ↓1`, and the panel reported git's advice text as an error. The two
+ * branches cannot be reconciled by moving a pointer; they need a merge commit,
+ * which is what `git pull` does by default. `--ff --no-rebase` states that
+ * explicitly instead of inheriting the user's `pull.rebase`/`pull.ff`: both
+ * were measured to change the answer (`pull.ff=only` reproduces the refusal,
+ * `pull.rebase=true` rewrites local commits), and a Sync button must not mean
+ * two different things per repository. A fast-forward still happens where one
+ * is possible — verified against a behind-only branch.
+ *
+ * **A merge that stops on a conflict is SUCCESS, not a failure.** Measured:
+ * the command exits 1 with `MERGE_HEAD` in place and `UU` rows in the status —
+ * the state the panel's operation bar exists to show. Throwing there reported
+ * the conflict as a failed sync and hid the bar's own instructions, so the
+ * caller checks for a started merge exactly as `expectStarted` does for a
+ * merge the user asked for.
  */
 export async function pullBranch(cwd: string): Promise<void> {
   if (!(await readUpstream(cwd))) return;
-  await expectOk(['pull', '--ff-only'], cwd, 120000);
+  const result = await runGit(['pull', '--ff', '--no-rebase', '--no-edit'], {
+    cwd,
+    timeout: 120_000,
+    maxBuffer: 1024 * 1024,
+  });
+  if (result.error) throw result.error;
+  if (result.exitCode === 0) return;
+  const state = await readGitState(cwd);
+  if (state.operation === 'merge') return;
+  throw new Error(
+    result.stderr.trim() || result.stdout.trim() || `git exited with code ${result.exitCode}`,
+  );
 }

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

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * What the Files panel lists.
+ *
+ * The panel used to drop a hardcoded set of names (`node_modules`, `.git`,
+ * `dist`, `build`) at every depth, which hid `packages/android/dist` — the
+ * built APKs — from the user with no way to reach it. There is now no name
+ * filter at all: every entry is listed, and the `ignored` flag (one
+ * `git check-ignore` per listing) is what marks the untracked ones for dimming.
+ *
+ * Driven against a real temp directory, because the listing stats every entry
+ * and asks git about it.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { listDirectoryEntries } from '@/server/lib/fs/listing';
+
+const roots: string[] = [];
+
+afterEach(() => {
+  while (roots.length > 0) fs.rmSync(roots.pop() as string, { recursive: true, force: true });
+});
+
+function makeRoot(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-listing-'));
+  roots.push(dir);
+  return dir;
+}
+
+function mkdirs(root: string, names: string[]): void {
+  for (const name of names) fs.mkdirSync(path.join(root, name), { recursive: true });
+}
+
+describe('listDirectoryEntries', () => {
+  test('lists every entry, node_modules and .git included', async () => {
+    const root = makeRoot();
+    mkdirs(root, ['src', 'dist', 'build', 'node_modules/preact', '.git/objects']);
+
+    const names = (await listDirectoryEntries(root, root)).map((entry) => entry.name);
+
+    expect(names).toContain('dist');
+    expect(names).toContain('build');
+    expect(names).toContain('src');
+    // No name table: the panel must be able to reach anything on disk.
+    expect(names).toContain('node_modules');
+    expect(names).toContain('.git');
+  });
+
+  test('a nested dist is listed where it lives, not filtered by name', async () => {
+    const root = makeRoot();
+    mkdirs(root, ['packages/android/dist', 'packages/core']);
+
+    const packages = await listDirectoryEntries(path.join(root, 'packages'), root);
+    expect(packages.map((entry) => entry.name)).toEqual(['android', 'core']);
+
+    const android = await listDirectoryEntries(path.join(root, 'packages/android'), root);
+    expect(android.map((entry) => entry.name)).toEqual(['dist']);
+    // Paths stay relative to the LISTED root, which is what the tree keys on,
+    // and they are POSIX-spelled whatever the platform: `path.relative` answers
+    // `packages\android\dist` on Windows, which keyed every row differently from
+    // the same row on POSIX and — because `git check-ignore` rejects a
+    // backslash — left the whole listing un-dimmed there. This assertion is the
+    // guard; it is what failed on the Windows CI leg.
+    expect(android[0]!.path).toBe('packages/android/dist');
+  });
+
+  test('folders sort before files, and dot-entries are listed', async () => {
+    const root = makeRoot();
+    fs.mkdirSync(path.join(root, 'zebra'));
+    fs.writeFileSync(path.join(root, 'alpha.txt'), '');
+    fs.writeFileSync(path.join(root, '.env'), 'K=1\n');
+
+    const entries = await listDirectoryEntries(root, root);
+    const names = entries.map((entry) => entry.name);
+
+    expect(entries[0]!.type).toBe('folder');
+    expect(names).toEqual(['zebra', '.env', 'alpha.txt']);
+  });
+});