@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/test-support/file-explorer.test-util.ts

@@ -7,14 +7,11 @@
  * The Files panel's test harness: a fake disk, a real realtime server, and the
  * click helpers the panel's specs drive it with.
  *
- * Extracted because TWO spec files exercise the same panel — the listing
- * behaviours and the root context menu — and each was carrying its own copy of
- * the mount, the HTTP stub and the click helpers. A second copy is how the two
- * files drift into testing different setups.
- *
- * The HTTP stub is a real directory model: specs mutate `disk` between reads,
- * which is what makes a refresh assertion fail on a panel that answered from
- * its children cache instead of from the server.
+ * Extracted because several spec files exercise the same panel, and each was
+ * carrying its own copy of the mount, the HTTP stub and the helpers. The HTTP
+ * stub is a real directory model (see `file-explorer-disk.test-util`): specs
+ * mutate `disk` between reads, which is what makes a refresh assertion fail on a
+ * panel that answered from its children cache instead of from the server.
  */
 
 import { Window } from 'happy-dom';
@@ -29,14 +26,13 @@ import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support
 import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
 import type { TopicResolver } from '@/server/lib/realtime/hub.server';
 import type { GitStatusPayload } from '@/server/lib/fs/git-status-read';
+import { diskHas, entriesOf, moveOnDisk, writeToDisk, type Disk } from '@/test-support/file-explorer-disk.test-util';
+
+export type { Disk } from '@/test-support/file-explorer-disk.test-util';
 
 export const ROOT = '/ws';
 export const SESSION = 'new-files-panel';
 const TOPIC = fsTopic(`${ROOT}\u0000.`);
-
-/** The fake disk: `path -> child -> (null for a folder, 'file' for a file)`. */
-export type Disk = Record<string, Record<string, null | 'file'> | undefined>;
-
 const GIT_STATUS: GitStatusPayload = { changes: [], branch: 'main', branches: [], remoteBranches: [] };
 
 export interface FileExplorerHarness {
@@ -46,9 +42,9 @@ export interface FileExplorerHarness {
   dirReads: string[];
   /** Paths whose NEXT read answers a non-JSON 500 (a transport failure). */
   failNext: Set<string>;
-  /** Every create the panel posted, as its form fields. */
+  /** Every create / rename / transfer the panel posted, as its form fields. */
   createRequests: Array<Record<string, string>>;
-  /** Every duplicate/paste the panel posted, as its form fields. */
+  renameRequests: Array<Record<string, string>>;
   transferRequests: Array<Record<string, string>>;
   /** Files the panel asked the editor to open, in order. */
   openedFiles: Array<{ path: string; name: string }>;
@@ -66,44 +62,36 @@ export interface FileExplorerHarness {
   panelBackground: () => HTMLElement;
   /** Right-click the background, leaving its menu open. */
   openMenuOnBackground: () => Promise<void>;
-  /** Right-click the background and click the menu's New File row. */
+  /** Right-click the background and click its New File / New Folder row. */
   openRootNewFile: () => Promise<void>;
+  openRootNewFolder: () => Promise<void>;
   /** Type a name into the open create dialog and submit it. */
   submitNewFile: (name: string) => Promise<void>;
+  /** Type a destination into the open rename dialog and submit it. */
+  submitRename: (path: string) => Promise<void>;
+  renameInput: () => HTMLInputElement | null;
+  /** Every row name the tree is currently drawing, in order. */
+  visibleNames: () => string[];
+  /** The whole rendered document's text — a dialog's inline refusal lives here. */
+  documentText: () => string;
   /** Every button label currently in the document — the menu assertions read it. */
   buttonLabels: () => string[];
   /** Click a button by its exact label (a context-menu row, a dialog action). */
   clickMenuRow: (label: string) => Promise<void>;
-  /**
-   * Drag the row named `from` onto the row named `to`, or onto the panel
-   * background when `to` is null — the whole gesture, in the order the browser
-   * raises it: dragstart on the source, dragover on the target (where a target
-   * refuses), then drop.
-   */
+  /** Drag `from` onto `to` (or the background when null): dragstart, dragover, drop. */
   dragRow: (from: string, to: string | null) => Promise<void>;
-  /** Install the DOM globals (call from `beforeAll`). */
+  /** DOM globals for the whole file (call from beforeAll / afterAll). */
   install: () => void;
-  /** Restore the runner's own globals (call from `afterAll`). */
   restore: () => void;
 }
 
-/** One directory's entries as the server emits them: folders with `children: null`. */
-function entriesOf(disk: Disk, path: string): unknown[] {
-  const dir = disk[path] ?? {};
-  return Object.keys(dir).map((child) => {
-    const rel = path === '.' ? child : `${path}/${child}`;
-    return dir[child] === null
-      ? { id: rel, name: child, type: 'folder', path: rel, children: null, ignored: false }
-      : { id: rel, name: child, type: 'file', path: rel, ignored: false };
-  });
-}
-
 export function createFileExplorerHarness(): FileExplorerHarness {
   const harness: FileExplorerHarness = {
     disk: {},
     dirReads: [],
     failNext: new Set(),
     createRequests: [],
+    renameRequests: [],
     transferRequests: [],
     openedFiles: [],
     container: null as unknown as HTMLElement,
@@ -127,6 +115,7 @@ export function createFileExplorerHarness(): FileExplorerHarness {
     async mount() {
       harness.failNext = new Set();
       harness.createRequests = [];
+      harness.renameRequests = [];
       harness.transferRequests = [];
       harness.openedFiles = [];
       // A fresh mount is a fresh session: the panel's per-session UI state
@@ -144,8 +133,8 @@ export function createFileExplorerHarness(): FileExplorerHarness {
       target.WebSocket = pristineWebSocket;
       target.fetch = async (input: unknown, init?: RequestInit) => {
         const url = String(input);
-        const json = (body: unknown) => new Response(JSON.stringify(body), {
-          status: 200,
+        const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), {
+          status,
           headers: { 'content-type': 'application/json' },
         });
         if (url.includes('/state')) return json({ sessionId: SESSION, state: {} });
@@ -161,11 +150,25 @@ export function createFileExplorerHarness(): FileExplorerHarness {
             harness.transferRequests.push(fields);
             return json({ success: true, path: `moved-${fields.actionType}` });
           }
+          if (fields.actionType === 'rename') {
+            harness.renameRequests.push(fields);
+            // The real route refuses an existing destination; the disk is the
+            // authority here too, so a refusal spec drives the same path.
+            const destination = fields.newPath;
+            if (destination !== fields.path && diskHas(harness.disk, destination)) {
+              return json({ error: `${destination} already exists` }, 409);
+            }
+            moveOnDisk(harness.disk, fields.path, destination);
+            return json({ success: true, path: destination, previousPath: fields.path });
+          }
           harness.createRequests.push(fields);
-          // The create route answers with the new file's path relative to the
+          // The create route answers with the new entry's path relative to the
           // LISTED root; the folder is `.` for the panel's own background menu.
-          const rel = fields.path === '.' ? fields.name : `${fields.path}/${fields.name}`;
-          return json({ success: true, path: rel });
+          // `kind` rides back because the tree draws a folder differently from a
+          // file, and the request is the only place it is stated.
+          const kind = fields.kind === 'folder' ? 'folder' : 'file';
+          const rel = writeToDisk(harness.disk, fields.path, fields.name, kind);
+          return json({ success: true, kind, path: rel });
         }
         if (url.includes('/api/fs/dir')) {
           const path = new URL(url, 'http://127.0.0.1').searchParams.get('path') ?? '.';
@@ -241,8 +244,36 @@ export function createFileExplorerHarness(): FileExplorerHarness {
       await harness.openMenuOnBackground();
       await harness.clickMenuRow('New File');
     },
+    async openRootNewFolder() {
+      await harness.openMenuOnBackground();
+      await harness.clickMenuRow('New Folder');
+    },
+    async submitRename(path) {
+      const input = harness.renameInput();
+      if (!input) throw new Error('no rename dialog');
+      await act(async () => {
+        input.value = path;
+        input.dispatchEvent(new window.Event('input', { bubbles: true }));
+      });
+      for (let i = 0; i < 5; i += 1) await act(async () => {});
+      await harness.clickMenuRow('Rename');
+      for (let i = 0; i < 20; i += 1) await act(async () => {});
+    },
+    renameInput() {
+      return document.querySelector('input[aria-label^="Rename "]') as HTMLInputElement | null;
+    },
+    visibleNames() {
+      // A row's name span is the leaf that carries it; the row wrapper reads the
+      // same text, so the SPAN is what is collected (one per row).
+      return [...harness.container.querySelectorAll('span')]
+        .map((el) => el.textContent?.trim() ?? '')
+        .filter((text) => text.length > 0);
+    },
+    documentText() {
+      return document.body.textContent ?? '';
+    },
     async submitNewFile(name) {
-      const input = document.querySelector('input[aria-label="New file name"]') as HTMLInputElement | null;
+      const input = document.querySelector('input[aria-label^="New "]') as HTMLInputElement | null;
       if (!input) throw new Error('no create dialog');
       await act(async () => {
         input.value = name;

package/src/test-support/loopback.ts

@@ -0,0 +1,183 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Real loopback listeners and real processes for the lifecycle suites.
+ *
+ * `probe`, `claimPort` and `findOccupant` all answer questions about sockets
+ * and PIDs, so a double would test the double: every case here drives actual
+ * listeners on OS-assigned ports and actual processes. The harness exists
+ * because those suites are split by subject (the address rules, the health
+ * probe, the lock, the claim) and each needs the same six fixtures — a copy per
+ * file is how one of them quietly stops covering both loopback families.
+ *
+ * Two properties are load-bearing:
+ *
+ *  - `localhost` is TWO addresses. A fixture that holds one family and expects
+ *    the other to read free must first find a port free on both, because the OS
+ *    assigns per family.
+ *  - A live PID that is not ours is what a test about ANOTHER instance needs:
+ *    the guard reads a listener reporting `process.pid` as this very process
+ *    re-binding (the `bun run --hot` case), which is the opposite of a refusal.
+ */
+
+import { expect } from 'bun:test';
+import type { Server } from 'bun';
+import net from 'node:net';
+
+import { getProcessState } from '@/server/lib/lifecycle/identity';
+import { isPortAvailable, waitForPortFree } from '@/server/lib/lifecycle/probe';
+
+/**
+ * The runner's own fetch, reached through `Bun` so a stub another file left on
+ * the global cannot be mistaken for it. Every case here talks to a real
+ * listener, and `findOccupant` asks one over `fetch`.
+ */
+export const realFetch = Bun.fetch;
+
+async function probeIpv6Loopback(): Promise<boolean> {
+  const { promise, resolve } = Promise.withResolvers<boolean>();
+  const probe = net.createServer();
+  probe.once('error', () => resolve(false));
+  probe.listen({ port: 0, host: '::1' }, () => {
+    probe.close(() => resolve(true));
+  });
+  return await promise;
+}
+
+/**
+ * Whether this host has a usable IPv6 loopback.
+ *
+ * A kernel booted without IPv6 answers `EADDRNOTAVAIL` for `::1`, where a
+ * case about the two addresses of `localhost` cannot observe anything at all.
+ * Skipped BY NAME rather than weakened: an assertion that silently holds on one
+ * family would pass while the bug was live.
+ */
+export const ipv6Loopback = await probeIpv6Loopback();
+
+export interface LoopbackHarness {
+  /** A live listener on an OS-assigned port, plus the number it got. */
+  occupy(
+    fetch: (request: Request) => Response | Promise<Response>,
+    hostname?: string,
+  ): { server: Server<undefined>; port: number };
+  /** A live listener on a specific port and address. */
+  occupyAt(port: number, hostname: string, fetch?: (request: Request) => Response): Server<undefined>;
+  /** An OS-assigned port, released and confirmed free. */
+  freePort(): Promise<number>;
+  /** An OS-assigned port free on BOTH loopback families. */
+  freePortBothFamilies(): Promise<number>;
+  /** A live process that is not this one; killed by `dispose`. */
+  livePid(): Promise<number>;
+  /** A real process whose argv says `kabmo`, i.e. `matched` to identity.ts. */
+  spawnChamberHolder(): Promise<Bun.Subprocess>;
+  /** A PID that has exited and been reaped, so it reads as `dead`. */
+  deadPid(): Promise<number>;
+  /** Stop every listener and kill every child this harness started. */
+  dispose(): Promise<void>;
+}
+
+export function createLoopbackHarness(): LoopbackHarness {
+  const servers: Server<undefined>[] = [];
+  const children: Bun.Subprocess[] = [];
+
+  function occupy(
+    fetch: (request: Request) => Response | Promise<Response>,
+    hostname = '127.0.0.1',
+  ): { server: Server<undefined>; port: number } {
+    const server = Bun.serve({ port: 0, hostname, fetch }) as Server<undefined>;
+    const port = server.port;
+    if (port === undefined) throw new Error('the OS did not assign an ephemeral port');
+    servers.push(server);
+    return { server, port };
+  }
+
+  function occupyAt(
+    port: number,
+    hostname: string,
+    fetch: (request: Request) => Response = () => new Response('held'),
+  ): Server<undefined> {
+    const server = Bun.serve({ port, hostname, fetch }) as Server<undefined>;
+    servers.push(server);
+    return server;
+  }
+
+  function forget(server: Server<undefined>): void {
+    const index = servers.indexOf(server);
+    if (index >= 0) servers.splice(index, 1);
+  }
+
+  async function freePort(): Promise<number> {
+    // Bun closes a stopped listener's socket on a later event-loop turn, so an
+    // immediate check would be a race, not a test.
+    const held = occupy(() => new Response('unused'));
+    held.server.stop(true);
+    forget(held.server);
+    if (!(await waitForPortFree(held.port, '127.0.0.1', 2_000, 25))) {
+      throw new Error(`ephemeral port ${held.port} never became free`);
+    }
+    return held.port;
+  }
+
+  async function freePortBothFamilies(): Promise<number> {
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+      const candidate = await freePort();
+      if (await isPortAvailable(candidate, '::1')) return candidate;
+    }
+    throw new Error('the OS handed out no ephemeral port free on both loopback families');
+  }
+
+  async function livePid(): Promise<number> {
+    const child = Bun.spawn({
+      cmd: ['bun', '-e', 'await new Promise(() => {})'],
+      stdout: 'ignore',
+      stderr: 'ignore',
+    });
+    children.push(child);
+    return child.pid;
+  }
+
+  async function spawnChamberHolder(): Promise<Bun.Subprocess> {
+    // The child announces itself before it parks, and that line is what says the
+    // OS has finished `exec`: a freshly spawned process's command line is
+    // unreadable for the instant between fork and exec, so Linux's probe falls
+    // back to `comm` and identity answers `mismatched` for a process that IS
+    // ours. Production reads a PID out of a lock file written long before, so it
+    // never sees that window — no fixed delay to guess at here.
+    const child = Bun.spawn({
+      cmd: ['bun', '-e', 'console.log("ready"); await new Promise(() => {})', 'kabmo-holder'],
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    children.push(child);
+    const reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
+    await reader.read();
+    reader.releaseLock();
+    expect(getProcessState(child.pid)).toBe('matched');
+    return child;
+  }
+
+  async function deadPid(): Promise<number> {
+    const child = Bun.spawn({ cmd: ['bun', '-e', 'process.exit(0)'], stdout: 'ignore', stderr: 'ignore' });
+    const pid = child.pid;
+    await child.exited;
+    expect(getProcessState(pid)).toBe('dead');
+    return pid;
+  }
+
+  async function dispose(): Promise<void> {
+    for (const child of children.splice(0)) {
+      try {
+        child.kill('SIGKILL');
+        await child.exited;
+      } catch {
+        // Already gone.
+      }
+    }
+    for (const server of servers.splice(0)) server.stop(true);
+  }
+
+  return { occupy, occupyAt, freePort, freePortBothFamilies, livePid, spawnChamberHolder, deadPid, dispose };
+}