@celilo/e2e 0.19.3 → 0.20.1

package/src/no-unjustified-sleep.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Recurrence gate for celilo#1267: readiness waits in packages/e2e must poll
+ * an observable condition (waitFor or a poll loop), never sleep a fixed
+ * duration.
+ *
+ * apps/celilo/CLAUDE.md prohibits sleeping to mask race conditions, but until
+ * now nothing enforced it in this package. respondWith slept 500ms for the
+ * responder to boot; on a loaded host that was not enough, the next command
+ * hit an unanswered interview, and the error read as a missing fixture value
+ * rather than as harness timing.
+ *
+ * The rule here: every fixed sleep in packages/e2e/src must carry an inline
+ * `e2e-sleep-ok:` justification on the same line or the line above. A poll
+ * loop's cadence sleep carries one honestly; a bare readiness gate cannot, so
+ * it fails this gate instead of failing five suites under load.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const SLEEP_PATTERN = /new Promise\(\s*\(?r\)?\s*=>\s*setTimeout\(r\s*,/;
+
+function srcDir(): string {
+  let dir = import.meta.dir;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'apps')) && existsSync(join(dir, 'modules')))
+      return join(dir, 'packages', 'e2e', 'src');
+    dir = resolve(dir, '..');
+  }
+  throw new Error('could not locate repo root (no ancestor with apps/ + modules/)');
+}
+
+function tsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...tsFiles(full));
+    else if (entry.endsWith('.ts') && !entry.endsWith('.test.ts')) out.push(full);
+  }
+  return out;
+}
+
+interface Violation {
+  file: string;
+  line: number;
+  text: string;
+}
+
+function unjustifiedSleeps(): Violation[] {
+  const violations: Violation[] = [];
+  for (const file of tsFiles(srcDir())) {
+    const lines = readFileSync(file, 'utf-8').split('\n');
+    lines.forEach((text, i) => {
+      if (!SLEEP_PATTERN.test(text)) return;
+      const justified = text.includes('e2e-sleep-ok:') || lines[i - 1]?.includes('e2e-sleep-ok:');
+      if (!justified) violations.push({ file, line: i + 1, text: text.trim() });
+    });
+  }
+  return violations;
+}
+
+describe('recurrence gate: no bare readiness sleeps in packages/e2e (celilo#1267)', () => {
+  test('the scan reaches a non-trivial set of files (sanity — it actually ran)', () => {
+    const files = tsFiles(srcDir());
+    expect(files.length).toBeGreaterThan(10);
+  });
+
+  test('every fixed sleep carries an e2e-sleep-ok justification', () => {
+    const violations = unjustifiedSleeps();
+    const report = violations
+      .map(
+        (v) =>
+          `${v.file}:${v.line}: ${v.text}\n  Add an inline \`e2e-sleep-ok: <reason>\` comment on this line or the one above, or poll an observable condition with waitFor.`,
+      )
+      .join('\n');
+    expect(violations, `Unjustified fixed sleeps:\n${report}`).toEqual([]);
+  });
+
+  test('the known poll-cadence sleeps are still present and justified (the rule engages)', () => {
+    // Reach probe, not reasoning: if the justified count drops to zero the
+    // scan is matching nothing and the gate above proves nothing.
+    const violations = unjustifiedSleeps();
+    const total = tsFiles(srcDir()).reduce((count, file) => {
+      const lines = readFileSync(file, 'utf-8').split('\n');
+      return count + lines.filter((text) => SLEEP_PATTERN.test(text)).length;
+    }, 0);
+    expect(total - violations.length).toBeGreaterThan(3);
+  });
+});

package/src/proxmox-provisioner.test.ts

@@ -9,6 +9,7 @@ import { describe, expect, test } from 'bun:test';
 import type { GuestRecord } from '@celilo/terraform-fake';
 import {
   CONTAINER_PREFIX,
+  GUEST_PROJECT_LABEL,
   containerNameFor,
   createDockerProvisioner,
   parseNet,
@@ -60,8 +61,10 @@ describe('createGuest', () => {
   });
 
   test('names the container so the debris sweep can find it', async () => {
-    // cele2e doctor and the by-name cleanup both key off this prefix; an
-    // unprefixed container leaks silently between runs.
+    // cele2e doctor keys off this prefix; an unprefixed container leaks
+    // silently between runs. Project membership is a separate concern — the
+    // per-test sweeps cannot match this name (no timestamp in it), so the
+    // label test below is what teardown actually keys off.
     const { runner, find } = stubDocker();
     await provisionerWith(runner).createGuest(guest());
 
@@ -70,6 +73,19 @@ describe('createGuest', () => {
     expect(name).toBe('celilo-e2e-lxc-203');
   });
 
+  test('labels the guest with its compose project so teardown can find it (celilo#1247)', async () => {
+    // The name cannot carry project membership (no timestamp), and compose's
+    // own labels cannot be borrowed (the guest is not a compose service, and
+    // compose down removes orphans only on the full label set — verified:
+    // a bare com.docker.compose.project label is not enough). The explicit
+    // label is what projectTeardownCommands lists guests by.
+    const { runner, find } = stubDocker();
+    await provisionerWith(runner).createGuest(guest());
+
+    const run = find('run') ?? [];
+    expect(run[run.indexOf('--label') + 1]).toBe(`${GUEST_PROJECT_LABEL}=celilo-e2e-test`);
+  });
+
   test('passes the gateway through, since target-setup routes from it', async () => {
     const { runner, find } = stubDocker();
     await provisionerWith(runner).createGuest(guest());

package/src/proxmox-provisioner.ts

@@ -30,6 +30,20 @@ import { ZONE_GATEWAYS, type Zone } from './types';
  */
 export const CONTAINER_PREFIX = 'celilo-e2e-';
 
+/**
+ * Marks a sim-created guest as belonging to a compose project.
+ *
+ * The name prefix alone is not enough for cleanup: a guest is named
+ * `celilo-e2e-lxc-<vmid>` with no timestamp in it, so every by-name filter the
+ * sweeps use (`celilo-e2e-1<ts>`, `celilo-e2e-<ts>`) misses it. A guest left
+ * behind keeps its zone network's endpoint alive, the network rm fails with
+ * "has active endpoints", and the subnet stays allocated — every later suite
+ * in the run then dies creating that network (celilo#1247). The label is what
+ * `projectTeardownCommands` filters on; it carries the project value, so
+ * teardown finds exactly the guests of the project it is tearing down.
+ */
+export const GUEST_PROJECT_LABEL = 'celilo-e2e.project';
+
 /** Shells out to `docker`. Injected so the logic is testable without a daemon. */
 export type DockerRunner = (args: string[]) => string;
 
@@ -71,6 +85,7 @@ export function zoneForGateway(gateway: string): Zone | undefined {
 export function createDockerProvisioner(options: DockerProvisionerOptions) {
   const docker = options.docker ?? realDocker;
   const readyTimeoutMs = options.readyTimeoutMs ?? 60_000;
+  // e2e-sleep-ok: injectable test seam; real callers poll a condition between sleeps.
   const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
 
   const assertOurs = (name: string): void => {
@@ -96,6 +111,12 @@ export function createDockerProvisioner(options: DockerProvisionerOptions) {
       const name = containerNameFor(guest.vmid);
       assertOurs(name);
 
+      // Project membership must be discoverable without the name: teardown
+      // matches on this label because the guest's name carries no timestamp.
+      // Added before the readiness wait, so even a guest that never finishes
+      // booting is still findable and removable.
+      const projectLabel = ['--label', `${GUEST_PROJECT_LABEL}=${options.project}`] as const;
+
       // Same image selection rule the compose generator uses for machines: the
       // app zone needs a dockerd-capable box.
       const image =
@@ -106,6 +127,7 @@ export function createDockerProvisioner(options: DockerProvisionerOptions) {
         '-d',
         '--name',
         name,
+        ...projectLabel,
         '--hostname',
         guest.hostname,
         '--network',

package/src/public-sim-routes.test.ts

@@ -34,7 +34,7 @@ const ISP_EDGE = '100.64.0.1';
 const EDGE_SERVICE = 'fw-ext';
 
 interface ComposeService {
-  build?: { dockerfile?: string };
+  image?: string;
   networks?: Record<string, unknown>;
 }
 
@@ -61,7 +61,14 @@ function publicSimulators(yaml: string): Array<{ name: string; dockerfile: strin
   const compose = parse(yaml) as { services?: Record<string, ComposeService> };
   return Object.entries(compose.services ?? {})
     .filter(([name, svc]) => name !== EDGE_SERVICE && svc.networks?.['internet-external'])
-    .map(([name, svc]) => ({ name, dockerfile: svc.build?.dockerfile ?? '' }));
+    .map(([name, svc]) => ({
+      name,
+      // The compose carries the tag, not the Dockerfile: the bake convention
+      // is tag `celilo-e2e/<name>` <-> `docker/Dockerfile.<name>` (build-infra
+      // tags every Dockerfile exactly that way). A drift in the convention
+      // makes the reads below fail loudly, which is what we want.
+      dockerfile: `docker/Dockerfile.${(svc.image ?? '').replace('celilo-e2e/', '').replace(/:.*/, '')}`,
+    }));
 }
 
 /**

package/src/repo-root.ts

@@ -0,0 +1,33 @@
+/**
+ * Where the celilo monorepo is, if we are inside one.
+ *
+ * Its own module because two unrelated consumers need it and neither may
+ * import the other: `cli/build.ts` uses it to find modules to package, and
+ * `doctor.ts` uses it to fingerprint the source a baked image came from —
+ * and `build.ts` already imports `doctor.ts`, so the reverse edge would be a
+ * cycle. Re-exported from `cli/build.ts` so its existing callers and its
+ * recurrence test are unchanged.
+ */
+
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/**
+ * Walk up from `startDir` to the celilo checkout, or null.
+ *
+ * The marker is `apps/celilo/package.json` and must stay that specific
+ * (ce-dbc): keying on a bare `modules/` directory made a stray empty
+ * `node_modules/modules` from a botched `bun add -g` read as the monorepo
+ * root, which skipped the published-staging path and crashed the packer for
+ * every npm consumer.
+ */
+export function findMonorepoRoot(startDir: string): string | null {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(dir, 'apps', 'celilo', 'package.json'))) return dir;
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}

package/src/run-args.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'bun:test';
+import { KNOWN_RUN_FLAGS, filterTestFilesByPatterns, parseRunArgs } from './run-args';
+
+describe('parseRunArgs', () => {
+  test('--help is recognized as help, never discarded into run-everything', () => {
+    const parsed = parseRunArgs(['--help']);
+    expect(parsed.helpRequested).toBe(true);
+    expect(parsed.unknownFlags).toEqual([]);
+    expect(parsed.patterns).toEqual([]);
+  });
+
+  test('every known flag is accepted and yields no patterns', () => {
+    const parsed = parseRunArgs([...KNOWN_RUN_FLAGS, '--seed=42']);
+    expect(parsed.unknownFlags).toEqual([]);
+    expect(parsed.patterns).toEqual([]);
+    expect(parsed.helpRequested).toBe(false);
+  });
+
+  test('positional patterns survive flag parsing in order', () => {
+    const parsed = parseRunArgs(['deploy', '--keep', 'caddy', '--verbose']);
+    expect(parsed.patterns).toEqual(['deploy', 'caddy']);
+    expect(parsed.unknownFlags).toEqual([]);
+  });
+
+  test('an unrecognised --flag is reported, not silently discarded', () => {
+    // The old runner stripped every --arg it did not know, leaving zero
+    // patterns: run everything. `--al` must error, not launch the catalogue.
+    const parsed = parseRunArgs(['--al', '--dry-run']);
+    expect(parsed.unknownFlags).toEqual(['--al', '--dry-run']);
+    expect(parsed.patterns).toEqual([]);
+    expect(parsed.helpRequested).toBe(false);
+  });
+
+  test('the CLI discovery aliases are unknown to the runner', () => {
+    // `cele2e run` strips --all/--all-modules before exec. If one ever
+    // reaches the runner directly it must error, not run everything.
+    const parsed = parseRunArgs(['--all', '--all-modules']);
+    expect(parsed.unknownFlags).toEqual(['--all', '--all-modules']);
+  });
+});
+
+describe('filterTestFilesByPatterns', () => {
+  const files = [
+    '/mods/knot/e2e/aspect-fanout.test.ts',
+    '/top/tests/aspect-fanout-new-systems.test.ts',
+    '/top/tests/caddy-internal-private.test.ts',
+  ];
+
+  test('an exact pattern selects only its own file, not the sibling it prefixes', () => {
+    // The old substring-OR filter dragged aspect-fanout-new-systems into
+    // `cele2e run aspect-fanout caddy-internal-private` whenever the
+    // top-level dir was in the collected set.
+    const picked = filterTestFilesByPatterns(files, ['aspect-fanout', 'caddy-internal-private']);
+    expect(picked).toEqual([
+      '/mods/knot/e2e/aspect-fanout.test.ts',
+      '/top/tests/caddy-internal-private.test.ts',
+    ]);
+  });
+
+  test('a pattern with no exact match keeps substring semantics', () => {
+    const picked = filterTestFilesByPatterns(files, ['fanout-new']);
+    expect(picked).toEqual(['/top/tests/aspect-fanout-new-systems.test.ts']);
+  });
+
+  test('several patterns union their matches', () => {
+    const picked = filterTestFilesByPatterns(files, ['aspect-fanout-new-systems', 'aspect-fanout']);
+    expect(picked).toEqual([
+      '/mods/knot/e2e/aspect-fanout.test.ts',
+      '/top/tests/aspect-fanout-new-systems.test.ts',
+    ]);
+  });
+
+  test('no patterns selects everything', () => {
+    expect(filterTestFilesByPatterns(files, [])).toEqual(files);
+  });
+});

package/src/run-args.ts

@@ -0,0 +1,89 @@
+import { basename } from 'node:path';
+
+/**
+ * Argument parsing for the e2e run script (runner.ts). Pure and side-effect
+ * free, so the runner's argv contract is unit-testable without touching
+ * Docker, the run-lock, or anything else main() reaches at import time.
+ */
+
+/**
+ * Flags `e2e-run` understands. `--seed=<n>` is value-carrying and recognized
+ * by prefix, not listed here.
+ */
+export const KNOWN_RUN_FLAGS: readonly string[] = [
+  '--keep',
+  '--reuse',
+  '--live',
+  '--published',
+  '--source-cli',
+  '--verbose',
+  '--ci',
+  '--no-ci',
+  '--complete',
+  // Passed through by `cele2e run` (harmless/no-op there, see cli/index.ts).
+  '--ci-safe',
+  '--notify',
+  '--shuffle',
+  '--no-interactive',
+];
+
+export interface ParsedRunArgs {
+  /** Positional suite-name patterns (substring match against test file names). */
+  patterns: string[];
+  /** `--`-prefixed arguments the runner does not know. Must be empty before a run starts. */
+  unknownFlags: string[];
+  /** True when `--help` was requested. */
+  helpRequested: boolean;
+}
+
+/**
+ * Split e2e-run argv into patterns and flags. Reports unrecognized `--` args
+ * in `unknownFlags` instead of discarding them: the old filter stripped every
+ * `--`-prefixed argument it did not know, so `cele2e run --help` (and any
+ * typo'd flag) left zero patterns, which is the runner's encoding of "run
+ * everything" — the one command an unsure operator types took the single most
+ * expensive resource in the city.
+ */
+export function parseRunArgs(argv: readonly string[]): ParsedRunArgs {
+  const patterns: string[] = [];
+  const unknownFlags: string[] = [];
+  let helpRequested = false;
+  for (const arg of argv) {
+    if (!arg.startsWith('--')) {
+      patterns.push(arg);
+      continue;
+    }
+    if (arg === '--help') {
+      helpRequested = true;
+    } else if (!isKnownFlag(arg)) {
+      unknownFlags.push(arg);
+    }
+  }
+  return { patterns, unknownFlags, helpRequested };
+}
+
+/**
+ * Filter collected test files by the run's positional patterns. A pattern
+ * that exactly equals a test name selects only that file; otherwise the old
+ * substring semantics apply. Without the exact rule, `cele2e run
+ * aspect-fanout caddy-internal-private` also ran aspect-fanout-new-systems:
+ * the substring OR matched the prefix whenever the top-level dir was in the
+ * collected set.
+ */
+export function filterTestFilesByPatterns(
+  files: readonly string[],
+  patterns: readonly string[],
+): string[] {
+  if (patterns.length === 0) return [...files];
+  const exactPatterns = new Set(
+    patterns.filter((p) => files.some((f) => basename(f, '.test.ts') === p)),
+  );
+  return files.filter((f) => {
+    const name = basename(f, '.test.ts');
+    return patterns.some((p) => (exactPatterns.has(p) ? name === p : name.includes(p)));
+  });
+}
+
+function isKnownFlag(arg: string): boolean {
+  return KNOWN_RUN_FLAGS.includes(arg) || arg.startsWith('--seed=');
+}