@celilo/e2e 0.7.17 → 0.9.0

package/src/shared-infra.ts

@@ -28,7 +28,33 @@ function run(cmd: string, opts?: { cwd?: string; timeout?: number }): string {
   }).trim();
 }
 
-let sharedInfraRunning = false;
+/**
+ * Remove ALL celilo-e2e-* Docker resources by name prefix (#212). Used at
+ * start-of-run, where the run-lock guarantees no other session's stack is live.
+ * Graceful compose-down of the shared project first (clean network detach),
+ * then a force sweep that catches orphans from any prior invocation regardless
+ * of compose-project name or the path that created them.
+ */
+function nukeE2eResources(e2eDir: string): void {
+  try {
+    run(`docker compose -f ${SHARED_COMPOSE_FILE} -p ${SHARED_PROJECT_NAME} down --volumes --remove-orphans`,
+      { cwd: e2eDir, timeout: 30_000 });
+  } catch {}
+  try {
+    const ids = run('docker ps -aq --filter name=celilo-e2e', { timeout: 10_000 });
+    if (ids.trim()) run(`docker rm -f ${ids.replace(/\n/g, ' ')}`, { timeout: 60_000 });
+  } catch {}
+  try {
+    const nets = run('docker network ls --format "{{.Name}}"')
+      .split('\n')
+      .filter((n) => n.startsWith('celilo-e2e'));
+    for (const net of nets) {
+      try { run(`docker network rm ${net}`, { timeout: 5_000 }); } catch {}
+    }
+  } catch {}
+  try { run('docker network prune -f', { timeout: 10_000 }); } catch {}
+  try { run('docker volume prune -f', { timeout: 10_000 }); } catch {}
+}
 
 /**
  * Check if the shared infrastructure is already running and healthy.
@@ -46,10 +72,8 @@ let sharedInfraRunning = false;
  *     per-test stack failed with "network … declared as external,
  *     but could not be found" when starting per-test services).
  *
- * Source of truth is Docker, never the module-local
- * `sharedInfraRunning` flag in isolation — each test file runs in a
- * fresh bun process so that flag is always `false` at startup. The
- * flag exists only as a within-process cache for redundant calls.
+ * Source of truth is always Docker — each test file runs in a fresh
+ * bun process, so there is no reliable in-process cache to lean on.
  */
 export function isSharedInfraRunning(): boolean {
   try {
@@ -58,20 +82,16 @@ export function isSharedInfraRunning(): boolean {
       { cwd: getE2eDir() },
     );
     if (containers.trim().length === 0) {
-      sharedInfraRunning = false;
       return false;
     }
     const networks = run('docker network ls --format "{{.Name}}"');
     const networkLines = networks.split('\n');
     const haveAll = Object.values(SHARED_NETWORKS).every((n) => networkLines.includes(n));
     if (!haveAll) {
-      sharedInfraRunning = false;
       return false;
     }
-    sharedInfraRunning = true;
     return true;
   } catch {
-    sharedInfraRunning = false;
     return false;
   }
 }
@@ -104,38 +124,14 @@ export async function ensureSharedInfra(): Promise<void> {
 
   const e2eDir = getE2eDir();
 
-  // Clean up any stale shared infra resources
+  // Start-of-run cleanup. We hold the run-lock here (acquired in the runner /
+  // build path before any docker mutation), so NO other session's stack is
+  // live — it is safe to remove EVERY celilo-e2e-* resource by name prefix.
+  // This self-heals orphans left by a crashed / cross-path / cross-checkout
+  // prior run (e.g. a botched-mount container that wedges the next `up`),
+  // which the old compose-project-scoped `down` couldn't see (#212).
   console.log('[progress:start] cleaning up stale shared infrastructure | shared infra cleanup complete');
-  try {
-    run(`docker compose -f ${SHARED_COMPOSE_FILE} -p ${SHARED_PROJECT_NAME} down --volumes --remove-orphans`,
-      { cwd: e2eDir, timeout: 30_000 });
-  } catch {}
-
-  // Also clean up any per-test projects that reference our networks
-  try {
-    const networks = run('docker network ls --format "{{.Name}}"')
-      .split('\n')
-      .filter(n => n.startsWith('celilo-e2e-') && !n.startsWith(`${SHARED_PROJECT_NAME}_`));
-    if (networks.length > 0) {
-      const projects = [...new Set(networks.map(n => n.replace(/_[^_]+$/, '')))];
-      for (const project of projects) {
-        try { run(`docker compose -p ${project} down --volumes --remove-orphans`, { timeout: 30_000 }); } catch {}
-      }
-    }
-  } catch {}
-
-  try { run('docker network prune -f', { timeout: 10_000 }); } catch {}
-  try { run('docker volume prune -f', { timeout: 10_000 }); } catch {}
-
-  // Force-remove any leftover networks by name
-  try {
-    const staleNets = run('docker network ls --format "{{.Name}}"')
-      .split('\n')
-      .filter(n => n.startsWith('celilo-e2e'));
-    for (const net of staleNets) {
-      try { run(`docker network rm ${net}`, { timeout: 5_000 }); } catch {}
-    }
-  } catch {}
+  nukeE2eResources(e2eDir);
 
   // Refresh the bundled registry-server source so Dockerfile.registry's
   // COPY resolves whether we're in the monorepo (regenerated from the
@@ -188,7 +184,6 @@ export async function ensureSharedInfra(): Promise<void> {
         { cwd: e2eDir, timeout: 10_000 },
       );
       if (result.trim().length > 0) {
-        sharedInfraRunning = true;
         console.log('[progress:done] shared infrastructure ready');
         return;
       }
@@ -237,21 +232,4 @@ export async function stopSharedInfra(): Promise<void> {
   } catch {
     // Best effort
   }
-  sharedInfraRunning = false;
-}
-
-/**
- * Execute a command in a shared infrastructure container.
- */
-export function sharedExec(container: string, cmd: string, timeoutMs = 60_000): { stdout: string; exitCode: number } {
-  try {
-    const stdout = run(
-      `docker compose -f ${SHARED_COMPOSE_FILE} -p ${SHARED_PROJECT_NAME} exec -T ${container} bash -c ${JSON.stringify(cmd)}`,
-      { cwd: getE2eDir(), timeout: timeoutMs },
-    );
-    return { stdout, exitCode: 0 };
-  } catch (err: unknown) {
-    const e = err as { stdout?: string; status?: number };
-    return { stdout: e.stdout?.toString() ?? '', exitCode: e.status ?? 1 };
-  }
 }

package/src/types.ts

@@ -193,11 +193,17 @@ export interface NetworkHandle {
   /** Resolve a DNS name from the management machine */
   dig(name: string): Promise<string>;
 
-  /** Wait for a condition with timeout */
+  /**
+   * Wait for a condition with timeout. On timeout, `onTimeout` (if given) is
+   * invoked to collect live-state diagnostics that are appended to the error —
+   * so a readiness failure self-diagnoses instead of speculating
+   * (e2e-confidence #255).
+   */
   waitFor(
     check: () => Promise<boolean>,
     timeoutMs: number,
     label: string,
+    onTimeout?: () => string | Promise<string>,
   ): Promise<void>;
 
   /**
@@ -342,6 +348,15 @@ export interface ResponderValues {
       secretValues?: Record<string, string>;
     }
   >;
+  /**
+   * Aspect-consent decisions (ISS-0027 / #262). When a headless deploy emits
+   * `aspect.required.<module>.<role>`, the responder replies `{ consented }`
+   * so a module's base_module_aspect fan-out is approved without a TTY and
+   * without `--accept-aspects` at import. Lookup precedence: `<module>.<role>`,
+   * then `<module>`, then the `'*'` wildcard. Absent → skipped (never
+   * silently approved). Passed straight through to `celilo events respond`.
+   */
+  aspects?: Record<string, boolean>;
 }
 
 export const ZONE_GATEWAYS: Record<Zone, string> = {

package/AGENTS.md

@@ -1,117 +0,0 @@
-# AGENTS.md — `@celilo/e2e`
-
-`@celilo/e2e` is a **simulated internet in Docker** for end-to-end testing of
-[celilo](https://celilo.computer)-deployed apps. It stands up a DNS hierarchy
-(root → TLD → registrar → recursive resolver), an ACME server (Pebble, standing
-in for Let's Encrypt), an ISP router + customer firewall with real iptables NAT,
-zoned LAN networks, and systemd target machines — then runs celilo *inside* it as
-if it were deploying to a real home lab. This file orients an AI agent to write
-and run those tests. **Read the in-package docs below before searching the web** —
-they are the source of truth.
-
-This file ships **inside the npm package**: the `./`-prefixed docs in the doc map
-are installed alongside it (grep them offline). Repo-relative entries point at the
-source repository, which the tarball does not carry.
-
-## Mental model (learn these five things)
-
-- **The sim is a faithful internet, not a convenience harness.** Public DNS only
-  ever answers with the customer firewall's *external* IP; the firewall DNATs
-  inbound to the right internal host. ACME challenges validate over the public
-  path. A test that "passes" by short-circuiting any of this is testing a placebo
-  — see **Inviolable rules** below.
-- **`network()` builder** — declare zones and the machines in them, `.start()` the
-  topology, drive celilo with `.celilo(...)`, assert, then `.stop()`. This is the
-  whole library surface (`import { network } from '@celilo/e2e'`).
-- **Zones** — `internal` (home LAN), `dmz`, `app`, `secure` are the customer-side
-  networks; `isp-external` / `internet-external` model the public internet. Public
-  IPs live only on the public networks; the firewall containers are the only place
-  the two address spaces meet (via NAT/DNAT).
-- **Two consumption modes** — as a **library** (`network()` in a `bun test` file)
-  or via the **`cele2e` CLI** (`cele2e run <test>`, `build-infra`, `list`). The
-  shared infra (`celilo-e2e-shared`) is a *global* Docker compose project,
-  independent of which checkout started it.
-- **`build-infra` gate** — anything baked into a Docker image (`docker/`,
-  `config/`, `simulators/`, installed package tarballs) needs `cele2e build-infra`
-  before it takes effect. Pure `src/*.ts` changes do not (bun runs TS directly).
-
-## Writing a test (the happy path)
-
-```ts
-import { test, expect } from 'bun:test';
-import { network } from '@celilo/e2e';
-
-test('caddy serves TLS in the dmz', async () => {
-  const net = await network()
-    .dmz({ caddy: '10.0.10.10' })   // machine name → zone-side IP
-    .start();
-  try {
-    await net.celilo('module import caddy');
-    await net.celilo('module deploy caddy --no-interactive');
-    // assert against the deployed service via the public path, not the container IP
-  } finally {
-    await net.stop();
-  }
-});
-```
-
-- Prefer the **fixtures** in `./src/fixtures.ts` (`CADDY_DEPLOYMENT`,
-  `FULL_STACK`, `TECHNITIUM_STACK`, …) over hand-rolling topology.
-- Drive **everything through the celilo CLI** or the module's documented surface —
-  never `docker exec` to hand-edit a deployed container's config (that's the bug
-  you're trying to catch).
-- Poll on the **observable condition** the deploy is meant to satisfy
-  (`VantageProbe`, DNS resolution, an HTTP header) — never `setTimeout` to mask a
-  race.
-
-## CLI you'll use
-
-```
-cele2e list                     # enumerate every test (module suites + top-level)
-cele2e build-infra              # rebuild Docker images (required after image-baked changes)
-cele2e run <test> [--keep]      # run one test; --keep leaves the network up for debugging
-cele2e run --all                # full regression (every suite); --all-modules = modules only
-```
-
-For Claude-driven / detached runs, fire via the repo wrapper
-`infra/scripts/cele2e-run.sh <test> [--keep|--build]` (fire-and-forget RUNID/LOG
-contract) rather than calling `cele2e run` from a long-lived watcher.
-
-## Inviolable rules (breaking any turns the suite into a placebo)
-
-1. **No RFC 1918 leaks past the public boundary.** Public DNS never serves an A
-   record pointing at `10/8`, `172.16/12`, or `192.168/16` — only the firewall's
-   external IP.
-2. **Don't collapse the topology to fix a timing/connectivity bug.** Fix the
-   *deployment ordering* (DNS record / DNAT rule / firewall opening in place
-   before the dependent step), not the simulation.
-3. **Public IPs only on the public networks.** Firewall containers bridge public
-   and private — the only place those spaces meet, and only via NAT/DNAT.
-4. **ACME challenges go through the public path** to the firewall's external IP.
-5. **DDNS updates modify *public* DNS** with the firewall's external IP, never an
-   internal target IP.
-
-Cheats (`/etc/hosts` overrides, `iptables -F`, `--insecure` in module code,
-hardcoded internal IPs, `|| true` on a celilo command, sleeping past a race) are
-fine for **bisecting** a failure but are never a **final solution** — confirm the
-hypothesis, then ship the real fix. Full list + rationale in `./README.md` and the
-repo `CLAUDE.md`.
-
-## Doc map (read in this order)
-
-Shipped **inside this package** (offline, grep-friendly):
-
-- `./README.md` — network architecture, machines, routing, DNS, simulators,
-  manual usage. Start here.
-- `./COVERAGE.md` — the array/object/map coverage audit (where N>1 paths are or
-  aren't exercised). Consult before adding a multi-element feature test.
-- `./src/index.ts` — the public library exports (`network`, types, probes).
-- `./src/fixtures.ts` — ready-made topology presets to build tests on.
-- `./src/types.ts` — `NetworkHandle`, `Zone`, `MachineSpec`, `Vantage`, and the
-  zone subnet/gateway constants.
-
-In the **source repo** (not carried in the tarball):
-
-- `infra/docs/RUNNING_CELE2E_TESTS.md` — the full operator guide; read before
-  running the suite for real.
-- `https://celilo.computer/docs` — hosted docs (LAN; the repo docs lead).

package/COVERAGE.md

@@ -1,60 +0,0 @@
-# E2E Test Coverage Audit
-
-This document tracks how well the e2e suite exercises capability and module
-fields whose type is `array`, `object`, or `map` — anywhere the framework's
-public API admits "more than one of X."
-
-## Why this exists
-
-A test that only ever uses N=1 will pass even when the multi-element path is
-broken. The bug fixed by `dns_registrar` 4.0.0 (see
-`apps/celilo/designs/DNS_REGISTRAR_MULTI_DOMAIN.md`) escaped the existing e2e
-suite for exactly this reason: the website-deploy-simple test put caddy, namecheap,
-and the website all on a single domain, and the multi-domain code path was
-never exercised.
-
-## Audit checklist
-
-For every capability and every module manifest, identify each field whose
-type is `array`, `object`, or `map`. For each one, ask:
-
-1. Does at least one e2e test exercise this field with **N > 1** distinct
-   values?
-2. Are those values **meaningfully different** (different domains, different
-   zones, different ports — not just "two of the same kind of thing")?
-3. Does the test assert behavior that would be **wrong if only the first
-   element worked**?
-
-Anywhere all three answers aren't "yes," that's a gap to either close (write
-the test) or document why it's intentionally deferred.
-
-## Coverage table
-
-| Field | N>1? | Meaningfully different? | Asserts non-first works? | Status |
-|---|---|---|---|---|
-| `namecheap.domains` | yes (`website-deploy-cross-domain`) | yes (different TLDs: `iamtheinternet.org` + `example.net`) | yes (verifies example.net DNS+TLS while iamtheinternet.org is canonical) | covered |
-| `namecheap.ddns_passwords` (per-domain map) | yes (same test) | yes (distinct passwords per domain) | yes (uses example.net's own password to update its A record) | covered |
-| `caddy.hostnames` | yes (`website-deploy-simple`) | partial (same domain in `website-deploy-simple.test.ts`); yes (cross-TLD in cross-domain test) | yes (cross-domain test serves a hostname that isn't `hostnames[0]`) | covered |
-| `iptables.exposed_services` | unclear — needs audit | — | — | **GAP** |
-| `public_web` registrations across modules | partial (`website-deploy-simple.test.ts` registers auth + website on the same domain) | needs cross-domain variant | partial | **GAP** |
-| `<every secret: object field>` | typically only one key | usually no | — | **AUDIT EACH** |
-
-## Closing the gaps
-
-- **`iptables.exposed_services`**: write an e2e that exposes two services
-  on the same machine via different ports and verifies both are reachable
-  from outside.
-- **`public_web` cross-domain**: extend `website-deploy-simple.test.ts` (or a new
-  test) to register routes on two different domains and verify each is
-  served by the right backend.
-- **secret object fields**: as modules using these grow (e.g. third-party
-  API integrations with multiple keys), add per-key tests.
-
-## New-module checklist
-
-When authoring a module, list every field whose type permits multiple
-values. For each, write at least one e2e or integration test that uses
-**N ≥ 2** with meaningfully different values. Add a row to the table
-above (or document why you've deferred it).
-
-See `design/MODULE_DEVELOPMENT_GUIDE.md` for the full new-module checklist.

package/config/dns/iamtheinternet.org.zone

@@ -1,16 +0,0 @@
-$ORIGIN iamtheinternet.org.
-$TTL 300
-
-@ IN SOA ns1.iamtheinternet.org. admin.iamtheinternet.org. (
-    2024020247 300 60 604800 300
-)
-
-; Public DNS — RFC 1918 addresses NEVER appear here. The whole point of
-; the e2e simulation is to model real internet connectivity, where
-; private IPs are unreachable from outside. All public-facing names
-; resolve to the firewall's external IP (100.100.0.100), which DNATs
-; inbound to the right internal host.
-@       IN NS   ns1.iamtheinternet.org.
-ns1     IN A    100.64.0.55
-@       IN A    0.0.0.0
-www     IN A    100.100.0.100