@celilo/e2e 0.19.2 → 0.20.0

package/src/cli/host.ts

@@ -0,0 +1,252 @@
+/**
+ * `cele2e host` — bring the Docker host up and down in the shape the rig needs.
+ *
+ * On Linux this is a no-op: docker runs on the host kernel. On macOS docker
+ * runs inside a colima VM whose memory and mount transport dominate how long a
+ * suite takes, and both are set at `colima start` — so "start colima" is not a
+ * neutral act, and everyone who typed it by hand got whatever colima's defaults
+ * or the last person's flags left behind. That is what this command replaces:
+ * one invocation, one policy, derived from the host it is running on.
+ *
+ * Three verbs, and the split between them is deliberate.
+ *
+ *   `status`  reads and reports. No side effects.
+ *   `up`      starts the VM, or reports precisely why a running one cannot be
+ *             brought into policy. It NEVER destroys anything.
+ *   `reset`   destroys the VM and recreates it. The only way to change the
+ *             mount type, and it costs the whole image cache, so it demands
+ *             `--yes` and refuses while the run-lock is held.
+ *
+ * `up` cannot fix a wrong mount type, and pretending otherwise would be worse
+ * than useless: colima accepts `--mount-type` on an existing VM, prints
+ * `'volume mount type' cannot be updated after initial setup, discarded`, and
+ * carries on with the old one. A command that appeared to fix it and did not
+ * would be exactly the "check that cannot reach its subject" failure this rig
+ * has a whole section about.
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+  type HostVmBudget,
+  activeProfile,
+  evaluateHostVm,
+  readHostFacts,
+  readHostVmFacts,
+  recommendedBudget,
+} from '../host-vm';
+import { lockStatus } from '../run-lock';
+
+const bold = '\x1b[1m';
+const dim = '\x1b[2m';
+const green = '\x1b[32m';
+const red = '\x1b[31m';
+const yellow = '\x1b[33m';
+const reset = '\x1b[0m';
+
+/** Is there a colima binary to drive? */
+function haveColima(): boolean {
+  return spawnSync('colima', ['version'], { stdio: 'ignore' }).status === 0;
+}
+
+function colimaRunning(profile: string): boolean {
+  return spawnSync('colima', ['status', '-p', profile], { stdio: 'ignore' }).status === 0;
+}
+
+/**
+ * The `colima start` a fresh VM should get.
+ *
+ * `vz` (Apple Virtualization) rather than qemu, because virtiofs needs it.
+ * Exported so the docs and the tests quote the same string the command runs
+ * rather than a transcription of it.
+ */
+export function colimaStartArgs(budget: HostVmBudget, profile: string): string[] {
+  return [
+    'start',
+    '-p',
+    profile,
+    '--vm-type',
+    'vz',
+    '--cpu',
+    String(budget.cpus),
+    '--memory',
+    String(budget.memoryGiB),
+    '--mount-type',
+    budget.mountType,
+  ];
+}
+
+function reportStatus(): number {
+  const profile = activeProfile();
+  const host = readHostFacts();
+  const facts = readHostVmFacts(profile);
+
+  console.log(`${bold}=== Docker host ===${reset}`);
+  console.log(`  host        ${host.cpus} CPU, ${host.memoryGiB} GiB`);
+
+  if (!facts) {
+    console.log('  VM          none — docker runs natively, no host policy applies');
+    return 0;
+  }
+
+  const budget = recommendedBudget(host, facts.vmType);
+  console.log(
+    `  VM          colima/${facts.profile} (${facts.vmType}): ${facts.cpus} CPU, ${facts.memoryGiB} GiB, ${facts.mountType} mounts`,
+  );
+  console.log(
+    `  policy      ${budget.cpus} CPU, ${budget.memoryGiB} GiB, ${budget.mountType} mounts`,
+  );
+  console.log(`  running     ${colimaRunning(profile) ? 'yes' : 'no'}`);
+  console.log('');
+
+  const { problems, needsRecreate } = evaluateHostVm(facts, host, budget);
+  if (problems.length === 0) {
+    console.log(`${green}The VM matches the policy.${reset}`);
+    return 0;
+  }
+  for (const problem of problems) console.log(`  ${yellow}!${reset} ${problem}`);
+  console.log('');
+  console.log(
+    needsRecreate
+      ? `  fix: ${bold}cele2e host reset --yes${reset}  ${dim}(destroys the VM and its image cache; budget one \`cele2e build-infra\`)${reset}`
+      : `  fix: ${bold}cele2e host up${reset}  ${dim}(restarts the VM; images survive)${reset}`,
+  );
+  return 1;
+}
+
+function bringUp(): number {
+  const profile = activeProfile();
+  const host = readHostFacts();
+  const existing = readHostVmFacts(profile);
+  const budget = recommendedBudget(host, existing?.vmType ?? 'vz');
+
+  if (!existing) {
+    console.log(
+      `${bold}Creating the colima VM${reset} ${dim}(${budget.cpus} CPU, ${budget.memoryGiB} GiB, ${budget.mountType} mounts)${reset}`,
+    );
+    const result = spawnSync('colima', colimaStartArgs(budget, profile), { stdio: 'inherit' });
+    return result.status ?? 1;
+  }
+
+  const { problems, needsRecreate } = evaluateHostVm(existing, host, budget);
+  if (needsRecreate) {
+    console.error(`${red}The running VM cannot be brought into policy by restarting it.${reset}`);
+    for (const problem of problems) console.error(`  ! ${problem}`);
+    console.error('');
+    console.error('colima discards a mount-type change on an existing VM, so the only fix is to');
+    console.error('recreate it. That deletes the local image cache and costs one full');
+    console.error(`${bold}cele2e build-infra${reset}. When you are ready:`);
+    console.error('');
+    console.error(`  ${bold}cele2e host reset --yes${reset}`);
+    return 1;
+  }
+
+  if (colimaRunning(profile) && problems.length === 0) {
+    console.log(`${green}Docker host already up and in policy.${reset}`);
+    return 0;
+  }
+
+  // Memory and CPU DO take on a restart, so a plain `colima start` with the
+  // budget is the fix for those.
+  console.log(
+    `${bold}Starting the colima VM${reset} ${dim}(${budget.cpus} CPU, ${budget.memoryGiB} GiB)${reset}`,
+  );
+  const result = spawnSync(
+    'colima',
+    ['start', '-p', profile, '--cpu', String(budget.cpus), '--memory', String(budget.memoryGiB)],
+    { stdio: 'inherit' },
+  );
+  return result.status ?? 1;
+}
+
+/**
+ * Refuse to touch the VM while a run holds the lock.
+ *
+ * Not hypothetical: stopping the VM under a live run killed a colleague's
+ * suite mid-flight on 2026-09-05, and because every per-test container carries
+ * `restart: unless-stopped`, the next VM boot resurrected that dead run's
+ * containers as orphans.
+ */
+function lockBlocks(action: string): boolean {
+  const lock = lockStatus();
+  if (lock.free || !lock.holder) return false;
+  console.error(`${red}Refusing to ${action}: the e2e run-lock is held.${reset}`);
+  console.error(
+    `  ${lock.holder.session} — ${lock.holder.state} ${lock.holder.test} (pid ${lock.holder.pid})`,
+  );
+  console.error('');
+  console.error('Poll with `cele2e status --json` (exit 0 = free, 3 = busy), or release a stack');
+  console.error('you know is abandoned with `cele2e down`.');
+  return true;
+}
+
+function bringDown(): number {
+  if (lockBlocks('stop the Docker host')) return 3;
+  const profile = activeProfile();
+  if (!readHostVmFacts(profile)) {
+    console.log('No colima VM to stop.');
+    return 0;
+  }
+  console.log(`${bold}Stopping the colima VM${reset}`);
+  return spawnSync('colima', ['stop', '-p', profile], { stdio: 'inherit' }).status ?? 1;
+}
+
+function resetVm(args: string[]): number {
+  if (!args.includes('--yes')) {
+    console.error(`${red}cele2e host reset DESTROYS the VM, including every built image.${reset}`);
+    console.error('');
+    console.error('It is the only way to change the mount transport, which colima fixes at');
+    console.error('creation. After it you must run `cele2e build-infra` before any test.');
+    console.error('');
+    console.error(`Re-run as ${bold}cele2e host reset --yes${reset} when that is what you want.`);
+    return 1;
+  }
+  if (lockBlocks('reset the Docker host')) return 3;
+
+  const profile = activeProfile();
+  const host = readHostFacts();
+  const budget = recommendedBudget(host, 'vz');
+
+  console.log(
+    `${bold}Deleting the colima VM${reset} ${dim}(every local image goes with it)${reset}`,
+  );
+  const deleted = spawnSync('colima', ['delete', '-p', profile, '--force'], { stdio: 'inherit' });
+  if ((deleted.status ?? 1) !== 0) return deleted.status ?? 1;
+
+  console.log(
+    `${bold}Creating it again${reset} ${dim}(${budget.cpus} CPU, ${budget.memoryGiB} GiB, ${budget.mountType} mounts)${reset}`,
+  );
+  const created = spawnSync('colima', colimaStartArgs(budget, profile), { stdio: 'inherit' });
+  if ((created.status ?? 1) !== 0) return created.status ?? 1;
+
+  console.log('');
+  console.log(
+    `${yellow}The image cache is empty. Run \`cele2e build-infra\` before any test.${reset}`,
+  );
+  return 0;
+}
+
+/** Route a `cele2e host <verb>`; returns the process exit code. */
+export function runHost(args: string[]): number {
+  const verb = args[0] ?? 'status';
+
+  if (!haveColima() && verb !== 'status') {
+    console.error('No `colima` binary found — nothing for `cele2e host` to drive.');
+    console.error('On Linux docker runs natively and there is no host VM to shape.');
+    return 1;
+  }
+
+  switch (verb) {
+    case 'status':
+      return reportStatus();
+    case 'up':
+      return bringUp();
+    case 'down':
+      return bringDown();
+    case 'reset':
+      return resetVm(args.slice(1));
+    default:
+      console.error(`Unknown host verb: ${verb}`);
+      console.error('Usage: cele2e host <status|up|down|reset>');
+      return 1;
+  }
+}

package/src/cli/index.ts

@@ -12,14 +12,15 @@
  *   cele2e shell [container]
  *   cele2e status
  *   cele2e doctor
+ *   cele2e host <status|up|down|reset>
  *   cele2e last [--json]
  *   cele2e load
  *   cele2e scaffold <test-name>
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { diagnose, formatHolderLine, formatReport } from '../doctor';
 import { readLastRun } from '../last-run';
@@ -33,7 +34,13 @@ import {
 } from '../run-lock';
 import { runBuild } from './build';
 import { generateBashCompletion, generateZshCompletion, getCompletions } from './completion';
-import { findAllModules, findModulesWithMatchingTest } from './module-discovery';
+import { runHost } from './host';
+import {
+  discoverSuiteTests,
+  findAllModules,
+  resolvePatternTarget,
+  resolveRunTargets,
+} from './module-discovery';
 import { runScaffold } from './scaffold';
 
 const PKG_DIR = resolve(import.meta.dir, '../..');
@@ -96,43 +103,6 @@ function resolveSuiteRoot(): string {
   return start;
 }
 
-/**
- * Enumerate every discoverable Docker e2e test (all module suites + the repo's
- * top-level e2e/tests/) as `{ name, file }`, sorted, with module tests first.
- */
-function discoverSuiteTests(suiteRoot: string): { name: string; file: string; group: string }[] {
-  const out: { name: string; file: string; group: string }[] = [];
-  for (const moduleDir of findAllModules(suiteRoot)) {
-    const tp = join(moduleDir, 'e2e');
-    const testsDir = existsSync(join(moduleDir, 'manifest.yml'))
-      ? resolve(moduleDir, readManifestTestsDir(join(moduleDir, 'manifest.yml')) ?? 'e2e')
-      : tp;
-    if (!existsSync(testsDir)) continue;
-    for (const f of readdirSync(testsDir)
-      .filter((f) => f.endsWith('.test.ts'))
-      .sort()) {
-      out.push({
-        name: f.replace(/\.test\.ts$/, ''),
-        file: join(testsDir, f),
-        group: basename(moduleDir),
-      });
-    }
-  }
-  const topLevel = join(suiteRoot, 'e2e', 'tests');
-  if (existsSync(topLevel)) {
-    for (const f of readdirSync(topLevel)
-      .filter((f) => f.endsWith('.test.ts'))
-      .sort()) {
-      out.push({
-        name: f.replace(/\.test\.ts$/, ''),
-        file: join(topLevel, f),
-        group: '(top-level)',
-      });
-    }
-  }
-  return out;
-}
-
 /**
  * Say out loud when we cleared this session's own kept stack. Silence would be
  * worse than the old refusal: the operator asked for a kept stack, and it is
@@ -173,6 +143,7 @@ Commands:
   shell [container] Shell into a running container (default: management)
   status            Show run-lock holder + network status (exit 3 if busy)
   doctor            Check the environment a run needs (run's implicit preflight)
+  host <verb>       Bring the Docker host VM up/down in the shape the rig needs
   last              Show the most recent run's results dir + counts
   release           Free a run-lock left by --keep/up (does not tear down)
   load              Load cached Docker images from tarball
@@ -187,6 +158,9 @@ Options for \`run\`:
   --live            Use live (non-simulated) internet
   --published       Use published .netapp packages
   --notify          Desktop notification when the run finishes (best-effort)
+  --source-cli      Run the celilo CLI from the mounted workspace instead of the
+                    one baked into the management image. Roughly doubles each
+                    celilo command's start-up; iterate without a \`build-infra\`
   --ci              Plain log output: one ✔/✗ line per step, no spinner
                     (auto-on when a CI env var is set; --no-ci forces off)
 
@@ -195,6 +169,13 @@ Options for \`up\`:
   --full-stack      Start with caddy, IDP, and DB machines
   --custom <json>   Custom machine spec JSON
 
+Verbs for \`host\` (macOS/colima; a no-op where docker runs natively):
+  status            Report the VM against the policy (exit 1 if out of policy)
+  up                Start it, or say exactly why a running one is out of policy
+  down              Stop it (refuses while the e2e run-lock is held)
+  reset --yes       Recreate it — the ONLY way to change the mount transport.
+                    DESTROYS every built image; budget one \`cele2e build-infra\`
+
 Options for \`down\`:
   --keep            Stop containers but preserve volumes
   --all             Also stop competing module containers
@@ -219,6 +200,8 @@ Examples:
   cele2e shell caddy                # debug running caddy container
   cele2e build-infra                # rebuild Docker images + repackage all modules
   cele2e build-infra --skip-modules # rebuild Docker images only (faster)
+  cele2e host status                # is the Docker host VM shaped for the rig?
+  cele2e run caddy-uninstall --source-cli  # run the WORKSPACE cli, not the baked one
   cele2e scaffold lunacycle-auth    # create tests/lunacycle-auth.test.ts
   cele2e completion zsh             # print zsh completion script
 `);
@@ -302,21 +285,29 @@ switch (command) {
 
     if (!cwdHasManifest) {
       if (positionals.length === 1) {
-        const matches = findModulesWithMatchingTest(process.cwd(), positionals[0]);
-        if (matches.length === 1) {
+        // Resolve the pattern against the FULL discovered suite (every module +
+        // the repo's top-level e2e/tests/), rooted at resolveSuiteRoot() like
+        // `list` and `--all`. The wrapper cd's into packages/e2e before
+        // exec'ing, so the old walk down from process.cwd() started below the
+        // repo root: a test name `cele2e list` printed came back "No test
+        // files matched" from `cele2e run <name>`.
+        const target = resolvePatternTarget(resolveSuiteRoot(), positionals[0]);
+        if (target?.kind === 'top-level') {
+          runScript('e2e-run', args, {
+            E2E_TEST_DIR: target.dir,
+            E2E_TESTS_PATH: target.testsPath,
+          });
+        } else if (target?.kind === 'module') {
           runScript('e2e-run', args, {
             E2E_TEST_DIR: stateDir,
-            E2E_MODULE_DIR: matches[0].moduleDir,
+            E2E_MODULE_DIR: target.moduleDir,
           });
-        }
-        if (matches.length > 1) {
-          console.error(`Multiple modules contain tests matching "${positionals[0]}":`);
-          for (const m of matches) {
-            console.error(`  ${basename(m.moduleDir)}: ${m.matchedTests.join(', ')}`);
+        } else if (target?.kind === 'ambiguous') {
+          console.error(`Multiple tests match "${positionals[0]}":`);
+          for (const m of target.matches) {
+            console.error(`  ${m.group}: ${m.name}`);
           }
-          console.error(
-            '\nDisambiguate by running from inside the module directory or passing its path.',
-          );
+          console.error('\nDisambiguate with a longer pattern (an exact name always wins).');
           process.exit(1);
         }
       } else if (positionals.length === 0) {
@@ -327,6 +318,33 @@ switch (command) {
             E2E_MODULE_DIRS: allModules.join('\n'),
           });
         }
+      } else {
+        // Several names: resolve each independently against the full suite
+        // and feed the runner's multi-module env (E2E_MODULE_DIRS /
+        // E2E_TOP_LEVEL_TESTS). The old fall-through ran top-level discovery
+        // only, so module suites reported "No test files matched" — which
+        // reads as a typo, not a limitation.
+        const resolved = resolveRunTargets(resolveSuiteRoot(), positionals);
+        if (resolved.kind === 'no-match') {
+          console.error(`No suite matches "${resolved.pattern}". List them: cele2e list`);
+          process.exit(1);
+        }
+        if (resolved.kind === 'ambiguous') {
+          console.error(`Multiple tests match "${resolved.pattern}":`);
+          for (const m of resolved.matches) {
+            console.error(`  ${m.group}: ${m.name}`);
+          }
+          console.error('\nDisambiguate with a longer pattern (an exact name always wins).');
+          process.exit(1);
+        }
+        const env: Record<string, string> = { E2E_TEST_DIR: stateDir };
+        if (resolved.modules.length > 0) {
+          env.E2E_MODULE_DIRS = resolved.modules.join('\n');
+        }
+        if (resolved.topLevel) {
+          env.E2E_TOP_LEVEL_TESTS = join(resolveSuiteRoot(), 'e2e', 'tests');
+        }
+        runScript('e2e-run', args, env);
       }
     }
 
@@ -467,6 +485,15 @@ switch (command) {
     break;
   }
 
+  case 'host': {
+    // Deliberately outside the run-lock: `status` is read-only, and `up`/`down`/
+    // `reset` take the lock's VERDICT (see host.ts lockBlocks) rather than the
+    // lock itself — taking it would make `cele2e host down` unable to report
+    // that somebody else's run is what stopped it.
+    process.exit(runHost(args));
+    break;
+  }
+
   case 'last': {
     // Which results directory was MINE? Inferring it from `ls -t results` returns
     // the newest run, which after a refused start is somebody else's — a suite

package/src/cli/module-discovery.ts

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 
 const MAX_DEPTH = 2;
@@ -75,22 +75,117 @@ function walkModules(cwd: string, visit: (moduleDir: string, testsPath: string)
   scan(cwd, 1);
 }
 
-export interface ModuleTestMatch {
-  moduleDir: string;
-  matchedTests: string[];
+export const TOP_LEVEL_GROUP = '(top-level)';
+
+export interface SuiteTest {
+  name: string;
+  file: string;
+  group: string;
+  /** Owning directory: the module dir, or the suite's `e2e/` dir for top-level entries. */
+  dir: string;
 }
 
 /**
- * Find modules under `cwd` whose e2e dir contains a test name including `pattern`.
- * Used by `cele2e run <pattern>` when invoked outside any module dir.
+ * Enumerate every discoverable Docker e2e test (all module suites + the repo's
+ * top-level e2e/tests/) sorted, with module tests first.
  */
-export function findModulesWithMatchingTest(cwd: string, pattern: string): ModuleTestMatch[] {
-  const results: ModuleTestMatch[] = [];
-  walkModules(cwd, (moduleDir, testsPath) => {
-    const matched = listTestNames(testsPath).filter((t) => t.includes(pattern));
-    if (matched.length > 0) results.push({ moduleDir, matchedTests: matched });
-  });
-  return results;
+export function discoverSuiteTests(suiteRoot: string): SuiteTest[] {
+  const out: SuiteTest[] = [];
+  for (const moduleDir of findAllModules(suiteRoot)) {
+    const testsDir = existsSync(join(moduleDir, 'manifest.yml'))
+      ? resolve(moduleDir, readManifestTestsDir(join(moduleDir, 'manifest.yml')) ?? 'e2e')
+      : join(moduleDir, 'e2e');
+    if (!existsSync(testsDir)) continue;
+    for (const f of readdirSync(testsDir)
+      .filter((f) => f.endsWith('.test.ts'))
+      .sort()) {
+      out.push({
+        name: f.replace(/\.test\.ts$/, ''),
+        file: join(testsDir, f),
+        group: basename(moduleDir),
+        dir: moduleDir,
+      });
+    }
+  }
+  const topLevel = join(suiteRoot, 'e2e', 'tests');
+  if (existsSync(topLevel)) {
+    for (const f of readdirSync(topLevel)
+      .filter((f) => f.endsWith('.test.ts'))
+      .sort()) {
+      out.push({
+        name: f.replace(/\.test\.ts$/, ''),
+        file: join(topLevel, f),
+        group: TOP_LEVEL_GROUP,
+        dir: dirname(topLevel),
+      });
+    }
+  }
+  return out;
+}
+
+export type PatternTarget =
+  | { kind: 'module'; moduleDir: string }
+  | { kind: 'top-level'; dir: string; testsPath: string }
+  | { kind: 'ambiguous'; matches: SuiteTest[] };
+
+/**
+ * Resolve a `cele2e run <pattern>` positional against the full discovered
+ * suite. Pattern semantics match the runner's filter: substring against the
+ * test name, with one exception — a pattern that exactly equals a test name
+ * wins outright, so a suite whose name prefixes another (`aspect-fanout` vs
+ * `aspect-fanout-new-systems`) stays reachable from the repo root instead of
+ * reading as permanently ambiguous. Returns null when nothing matches, so the
+ * caller can fall through to its default tests dir.
+ */
+export function resolvePatternTarget(suiteRoot: string, pattern: string): PatternTarget | null {
+  const tests = discoverSuiteTests(suiteRoot);
+  const exact = tests.filter((t) => t.name === pattern);
+  if (exact.length === 1) {
+    return toPatternTarget(exact[0]);
+  }
+  if (exact.length > 1) {
+    return { kind: 'ambiguous', matches: exact };
+  }
+  const matches = tests.filter((t) => t.name.includes(pattern));
+  if (matches.length === 0) return null;
+  if (matches.length > 1) return { kind: 'ambiguous', matches };
+  return toPatternTarget(matches[0]);
+}
+
+function toPatternTarget(match: SuiteTest): PatternTarget {
+  if (match.group === TOP_LEVEL_GROUP) {
+    return { kind: 'top-level', dir: match.dir, testsPath: join(match.dir, 'tests') };
+  }
+  return { kind: 'module', moduleDir: match.dir };
+}
+
+export type RunTargets =
+  | { kind: 'ok'; modules: string[]; topLevel: boolean }
+  | { kind: 'no-match'; pattern: string }
+  | { kind: 'ambiguous'; pattern: string; matches: SuiteTest[] };
+
+/**
+ * Resolve every `cele2e run <name>...` positional independently and aggregate
+ * the targets into the env-shaped set the runner consumes: module dirs (for
+ * E2E_MODULE_DIRS) plus a top-level flag (for E2E_TOP_LEVEL_TESTS). Reports
+ * the FIRST unresolvable name rather than silently dropping it, so a typo or
+ * an un-followable ambiguity errors instead of falling through to a
+ * top-level-only run that prints "No test files matched".
+ */
+export function resolveRunTargets(suiteRoot: string, patterns: readonly string[]): RunTargets {
+  const modules = new Set<string>();
+  let topLevel = false;
+  for (const pattern of patterns) {
+    const target = resolvePatternTarget(suiteRoot, pattern);
+    if (!target) return { kind: 'no-match', pattern };
+    if (target.kind === 'ambiguous') return { kind: 'ambiguous', pattern, matches: target.matches };
+    if (target.kind === 'module') {
+      modules.add(target.moduleDir);
+    } else {
+      topLevel = true;
+    }
+  }
+  return { kind: 'ok', modules: Array.from(modules).sort(), topLevel };
 }
 
 /**

package/src/cli/scaffold.ts

@@ -3,6 +3,7 @@
  */
 
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+
 import { join } from 'node:path';
 
 const green = '\x1b[32m';
@@ -32,28 +33,23 @@ function generateTestTemplate(name: string): string {
  * Run (reuse): cele2e run --reuse ${name}
  */
 
-import { afterAll, describe, expect, test } from 'bun:test';
-import { network, progress, reconnectNetwork } from '@celilo/e2e';
+import { afterAll, describe, expect } from 'bun:test';
+import { createStages, network, progress, reconnectNetwork } from '@celilo/e2e';
 import type { NetworkHandle } from '@celilo/e2e/types';
 
 const REUSE = process.argv.includes('--reuse');
 const PROJECT_NAME = 'celilo-e2e-${name}';
 
 describe('${name}', () => {
-  let net: NetworkHandle;
-  let stageError: string | null = null;
+  const { stage } = createStages();
 
-  function requireStage(stage: string) {
-    if (stageError) {
-      throw new Error(\`Skipped: \${stage} — \${stageError}\`);
-    }
-  }
+  let net: NetworkHandle;
 
   afterAll(async () => {
     await net?.stop();
   });
 
-  test('start network', async () => {
+  stage('start network', async () => {
     if (REUSE) {
       net = await reconnectNetwork(PROJECT_NAME);
       return;
@@ -65,24 +61,20 @@ describe('${name}', () => {
       .start();
   }, 120_000);
 
-  test('deploy', async () => {
-    requireStage('deploy');
-    try {
-      progress('importing module', 'module imported');
-      await net.celilo('module import /path/to/module.netapp');
-      progress.done();
-
-      progress('deploying', 'deployed');
-      await net.celilo('module deploy my-module');
-      progress.done();
-    } catch (error) {
-      stageError = String(error);
-      throw error;
-    }
+  // Each stage runs as its own bun test with its own timeout. If a stage fails
+  // or times out, the later stages skip with a 'Skipped: ...' reason naming
+  // the cause, instead of running against a half-built fixture.
+  stage('deploy', async () => {
+    progress('importing module', 'module imported');
+    await net.celilo('module import /path/to/module.netapp');
+    progress.done();
+
+    progress('deploying', 'deployed');
+    await net.celilo('module deploy my-module');
+    progress.done();
   }, 300_000);
 
-  test('verify', async () => {
-    requireStage('verify');
+  stage('verify', async () => {
     // TODO: add verification steps
     // const result = await net.exec('machine-1', 'curl -s http://localhost');
     // expect(result.exitCode).toBe(0);