@celilo/e2e 0.5.1 → 0.6.1

package/src/cli/index.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+/**
+ * cele2e — E2E test CLI for Celilo-deployed applications.
+ *
+ * Usage:
+ *   cele2e run [pattern] [--keep] [--reuse] [--live] [--published]
+ *   cele2e up [--caddy|--full-stack|--infrastructure|--custom '<json>']
+ *   cele2e down [--keep] [--all]
+ *   cele2e build-infra [module-dir...] [--save]
+ *   cele2e clear-timing
+ *   cele2e version
+ *   cele2e shell [container]
+ *   cele2e status
+ *   cele2e load
+ *   cele2e scaffold <test-name>
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { runBuild } from './build';
+import { runScaffold } from './scaffold';
+import { generateBashCompletion, generateZshCompletion, getCompletions } from './completion';
+import { findAllModules, findModulesWithMatchingTest } from './module-discovery';
+
+const PKG_DIR = resolve(import.meta.dir, '../..');
+const BIN_DIR = join(PKG_DIR, 'bin');
+
+
+function readManifestTestsDir(manifestPath: string): string | undefined {
+  try {
+    const parsed = parseYaml(readFileSync(manifestPath, 'utf-8')) as { e2e?: { tests_dir?: string } };
+    return parsed?.e2e?.tests_dir;
+  } catch {
+    return undefined;
+  }
+}
+
+function detectTestDir(): { stateDir: string; testsPath: string } {
+  if (process.env.E2E_TEST_DIR) {
+    const stateDir = process.env.E2E_TEST_DIR;
+    return { stateDir, testsPath: join(stateDir, 'tests') };
+  }
+  const cwd = process.cwd();
+  const manifestPath = join(cwd, 'manifest.yml');
+  if (existsSync(manifestPath)) {
+    const testsDir = readManifestTestsDir(manifestPath);
+    if (testsDir) {
+      const testsPath = resolve(cwd, testsDir);
+      return { stateDir: dirname(testsPath), testsPath };
+    }
+  }
+  if (existsSync(join(cwd, 'tests'))) return { stateDir: cwd, testsPath: join(cwd, 'tests') };
+  return { stateDir: cwd, testsPath: join(cwd, 'tests') };
+}
+
+function runScript(script: string, args: string[], env?: Record<string, string>): never {
+  const result = spawnSync(join(BIN_DIR, script), args, {
+    stdio: 'inherit',
+    env: { ...process.env, ...env },
+  });
+  process.exit(result.status ?? 1);
+}
+
+function printHelp(): void {
+  console.log(`
+cele2e — E2E test CLI for Celilo-deployed applications
+
+Usage:
+  cele2e <command> [options]
+
+Commands:
+  run [pattern]     Run e2e tests (pattern filters by test file name)
+  up [preset]       Start interactive test network
+  down              Tear down running network
+  build-infra [dirs...] Rebuild Docker images and package all modules as .netapps
+  clear-timing      Clear saved timing history used for test ETAs
+  version           Show cele2e version
+  shell [container] Shell into a running container (default: management)
+  status            Show network status and DNS health
+  load              Load cached Docker images from tarball
+  scaffold <name>   Generate a new test file from template
+  completion <shell> Generate shell completion script (zsh|bash)
+
+Options for \`run\`:
+  --keep            Keep network running after tests
+  --reuse           Reuse existing network if running
+  --live            Use live (non-simulated) internet
+  --published       Use published .netapp packages
+
+Options for \`up\`:
+  --caddy           Start with caddy machine in DMZ
+  --full-stack      Start with caddy, IDP, and DB machines
+  --custom <json>   Custom machine spec JSON
+
+Options for \`down\`:
+  --keep            Stop containers but preserve volumes
+  --all             Also stop competing module containers
+
+Options for \`build-infra\`:
+  --save            Save Docker images to tarball after build
+  --skip-modules    Skip .netapp packaging (only rebuild Docker images)
+
+Examples:
+  cele2e run                        # in a module: run its tests; outside: run all modules' tests
+  cele2e run deploy                 # run tests matching "deploy"
+  cele2e run caddy-direct-internet  # from modules/, finds the matching module automatically
+  cele2e run --reuse deploy         # reuse existing network
+  cele2e up --full-stack            # interactive full-stack environment
+  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 scaffold lunacycle-auth    # create tests/lunacycle-auth.test.ts
+  cele2e completion zsh             # print zsh completion script
+`);
+}
+
+const [, , command, ...args] = process.argv;
+const { stateDir, testsPath: detectedTestsPath } = detectTestDir();
+
+// Handle --get-completions before routing (used by shell completion scripts)
+if (command === '--get-completions') {
+  const words = args.slice(0, -1);
+  const current = Number.parseInt(args[args.length - 1] || '0', 10);
+  const suggestions = getCompletions(words, current);
+  process.stdout.write(`${suggestions.join('\n')}\n`);
+  process.exit(0);
+}
+
+switch (command) {
+  case 'run': {
+    // Check if any non-flag arg is a module path (has manifest.yml)
+    const modulePath = args
+      .filter((a) => !a.startsWith('--'))
+      .find((a) => existsSync(join(resolve(a), 'manifest.yml')));
+
+    if (modulePath) {
+      const absModulePath = resolve(modulePath);
+      runScript('e2e-run', args.filter((a) => a !== modulePath), {
+        E2E_TEST_DIR: stateDir,
+        E2E_MODULE_DIR: absModulePath,
+      });
+    }
+
+    // If cwd is not a module, walk sibling modules so the user can invoke
+    // `cele2e run` from infra/modules/ (or the repo root) without cd-ing in.
+    const cwdHasManifest = existsSync(join(process.cwd(), 'manifest.yml'));
+    const positionals = args.filter((a) => !a.startsWith('--'));
+
+    if (!cwdHasManifest) {
+      if (positionals.length === 1) {
+        const matches = findModulesWithMatchingTest(process.cwd(), positionals[0]);
+        if (matches.length === 1) {
+          runScript('e2e-run', args, {
+            E2E_TEST_DIR: stateDir,
+            E2E_MODULE_DIR: matches[0].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(', ')}`);
+          }
+          console.error('\nDisambiguate by running from inside the module directory or passing its path.');
+          process.exit(1);
+        }
+      } else if (positionals.length === 0) {
+        const allModules = findAllModules(process.cwd());
+        if (allModules.length > 0) {
+          runScript('e2e-run', args, {
+            E2E_TEST_DIR: stateDir,
+            E2E_MODULE_DIRS: allModules.join('\n'),
+          });
+        }
+      }
+    }
+
+    runScript('e2e-run', args, { E2E_TEST_DIR: stateDir, E2E_TESTS_PATH: detectedTestsPath });
+    break;
+  }
+
+  case 'up':
+    runScript('e2e-up', args);
+
+  case 'down':
+    runScript('e2e-down', args, { E2E_TEST_DIR: stateDir });
+
+  case 'shell':
+    runScript('e2e-shell', args);
+
+  case 'status': {
+    const persistentFile = join(stateDir, '.e2e-persistent.json');
+    let projectName: string | undefined;
+    if (existsSync(persistentFile)) {
+      try {
+        const data = JSON.parse(readFileSync(persistentFile, 'utf-8'));
+        projectName = data.projectName;
+        console.log('=== Persistent Test Network ===');
+        console.log(`  Project:  ${data.projectName}`);
+        console.log(`  Test:     ${data.testFile}`);
+        console.log(`  Created:  ${data.createdAt}`);
+        console.log(`  Reuse:    cele2e run --reuse`);
+        console.log(`  Tear down: cele2e down`);
+        console.log('');
+      } catch { /* ignore parse errors */ }
+    }
+    runScript('e2e-status', args, projectName ? { CELILO_E2E_PROJECT: projectName } : undefined);
+  }
+
+  case 'load':
+    runScript('e2e-load', args);
+
+  case 'build-infra': {
+    const save = args.includes('--save');
+    const skipModules = args.includes('--skip-modules');
+    const moduleDirs = args.filter((a) => !a.startsWith('--'));
+    runBuild({ pkgDir: PKG_DIR, moduleDirs, save, skipModules });
+    break;
+  }
+
+  case 'clear-timing': {
+    const timingFile = join(stateDir, '.e2e-timing.json');
+    if (existsSync(timingFile)) {
+      rmSync(timingFile);
+      console.log(`Cleared timing data: ${timingFile}`);
+    } else {
+      console.log(`No timing data found at ${timingFile}`);
+    }
+    break;
+  }
+
+  case 'scaffold': {
+    const name = args[0];
+    if (!name) {
+      console.error('Error: scaffold requires a test name\n  cele2e scaffold <name>');
+      process.exit(1);
+    }
+    runScaffold({ testsPath: detectedTestsPath, name });
+    break;
+  }
+
+  case 'version': {
+    const pkg = await import('../../package.json', { with: { type: 'json' } });
+    console.log(`cele2e v${pkg.default.version}`);
+    break;
+  }
+
+  case 'completion': {
+    const shell = args[0];
+    if (shell === 'zsh') {
+      process.stdout.write(generateZshCompletion());
+    } else if (shell === 'bash') {
+      process.stdout.write(generateBashCompletion());
+    } else {
+      console.error('Usage: cele2e completion <zsh|bash>');
+      process.exit(1);
+    }
+    break;
+  }
+
+  case undefined:
+  case '--help':
+  case '-h':
+  case 'help':
+    printHelp();
+    break;
+
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    printHelp();
+    process.exit(1);
+}

package/src/cli/module-discovery.ts

@@ -0,0 +1,120 @@
+/**
+ * Walks the cwd tree to find Celilo modules and their e2e tests.
+ *
+ * Used so that `cele2e run <test-name>` works from `infra/modules/` (or the
+ * repo root) without needing to cd into the module first, and so tab
+ * completion can suggest test names discovered across all modules.
+ *
+ * Scans direct subdirs and one level deeper — covers `modules/` (where each
+ * subdir is a module) and `infra/` (where `modules/<name>/` is one level
+ * deeper).
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+const MAX_DEPTH = 2;
+
+function readManifestTestsDir(manifestPath: string): string | undefined {
+  try {
+    const parsed = parseYaml(readFileSync(manifestPath, 'utf-8')) as { e2e?: { tests_dir?: string } };
+    return parsed?.e2e?.tests_dir;
+  } catch {
+    return undefined;
+  }
+}
+
+function listTestNames(testsPath: string): string[] {
+  if (!existsSync(testsPath)) return [];
+  try {
+    return readdirSync(testsPath)
+      .filter((f) => f.endsWith('.test.ts'))
+      .map((f) => f.replace(/\.test\.ts$/, ''));
+  } catch {
+    return [];
+  }
+}
+
+function isModule(dir: string): { manifestPath: string; testsPath: string } | null {
+  const manifestPath = join(dir, 'manifest.yml');
+  if (!existsSync(manifestPath)) return null;
+  // Match the runner's resolution: prefer e2e.tests_dir from the manifest,
+  // fall back to a conventional e2e/ directory at the module root.
+  const testsDir = readManifestTestsDir(manifestPath) ?? 'e2e';
+  return { manifestPath, testsPath: resolve(dir, testsDir) };
+}
+
+function walkModules(cwd: string, visit: (moduleDir: string, testsPath: string) => void): void {
+  function scan(dir: string, depth: number): void {
+    if (depth > MAX_DEPTH) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.startsWith('.') || entry === 'node_modules') continue;
+      const subdir = join(dir, entry);
+      try {
+        if (!statSync(subdir).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      const mod = isModule(subdir);
+      if (mod) {
+        visit(subdir, mod.testsPath);
+      } else if (depth < MAX_DEPTH) {
+        scan(subdir, depth + 1);
+      }
+    }
+  }
+  scan(cwd, 1);
+}
+
+export interface ModuleTestMatch {
+  moduleDir: string;
+  matchedTests: 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.
+ */
+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;
+}
+
+/**
+ * Collect all test names reachable from `cwd`. Includes tests in cwd itself
+ * (when cwd is a module) and tests in any module discovered under cwd.
+ */
+export function findAllTestNames(cwd: string): string[] {
+  const names = new Set<string>();
+  const cwdMod = isModule(cwd);
+  if (cwdMod) {
+    for (const n of listTestNames(cwdMod.testsPath)) names.add(n);
+  }
+  walkModules(cwd, (_moduleDir, testsPath) => {
+    for (const n of listTestNames(testsPath)) names.add(n);
+  });
+  return Array.from(names).sort();
+}
+
+/**
+ * Return the absolute paths of all modules discoverable under `cwd` that have
+ * an e2e tests directory containing at least one `*.test.ts` file.
+ */
+export function findAllModules(cwd: string): string[] {
+  const modules: string[] = [];
+  walkModules(cwd, (moduleDir, testsPath) => {
+    if (listTestNames(testsPath).length > 0) modules.push(moduleDir);
+  });
+  return modules.sort();
+}

package/src/cli/scaffold.ts

@@ -0,0 +1,108 @@
+/**
+ * cele2e scaffold — generate a new e2e test file from template.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const green = '\x1b[32m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+interface ScaffoldOptions {
+  testsPath: string;
+  name: string;
+}
+
+function toTitleCase(kebab: string): string {
+  return kebab
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function generateTestTemplate(name: string): string {
+  const title = toTitleCase(name);
+  return `/**
+ * ${title} E2E Test
+ *
+ * Tests that ${title} deploys and operates correctly through Celilo's infrastructure.
+ *
+ * Run: cele2e run ${name}
+ * Run (reuse): cele2e run --reuse ${name}
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import { 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;
+
+  function requireStage(stage: string) {
+    if (stageError) {
+      throw new Error(\`Skipped: \${stage} — \${stageError}\`);
+    }
+  }
+
+  afterAll(async () => {
+    await net?.stop();
+  });
+
+  test('start network', async () => {
+    if (REUSE) {
+      net = await reconnectNetwork(PROJECT_NAME);
+      return;
+    }
+
+    net = await network({ projectName: PROJECT_NAME })
+      .dmz({ 'machine-1': '10.0.10.10' })
+      // .app({ 'app-1': '10.0.20.10' })
+      .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;
+    }
+  }, 300_000);
+
+  test('verify', async () => {
+    requireStage('verify');
+    // TODO: add verification steps
+    // const result = await net.exec('machine-1', 'curl -s http://localhost');
+    // expect(result.exitCode).toBe(0);
+  }, 60_000);
+});
+`;
+}
+
+export function runScaffold(options: ScaffoldOptions): void {
+  const { testsPath, name } = options;
+
+  mkdirSync(testsPath, { recursive: true });
+
+  const outPath = join(testsPath, `${name}.test.ts`);
+  if (existsSync(outPath)) {
+    console.error(`Error: ${outPath} already exists`);
+    process.exit(1);
+  }
+
+  writeFileSync(outPath, generateTestTemplate(name));
+  console.log(`${green}✔${reset} Created ${outPath}`);
+  console.log(`\n${dim}Run it with:\n  cele2e run ${name}${reset}`);
+}