@lamalibre/install-portlama-e2e-mcp 0.1.0

package/bin/install-portlama-e2e-mcp.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// ============================================================================
+// e2e-mcp — Dual-mode entry point
+// ============================================================================
+// Interactive (TTY):  Install mode — configures Claude Code MCP settings
+// Piped (stdio):      Server mode — runs as MCP server
+//
+// Usage:
+//   npx @lamalibre/install-portlama-e2e-mcp              # install & configure
+//   npx @lamalibre/install-portlama-e2e-mcp --install    # force install mode
+//   npx @lamalibre/install-portlama-e2e-mcp --server     # force server mode
+// ============================================================================
+
+const args = process.argv.slice(2);
+const forceInstall = args.includes('--install');
+const forceServer = args.includes('--server');
+
+try {
+  if (forceServer) {
+    await import('../src/index.js');
+  } else if (forceInstall || process.stdin.isTTY) {
+    const { install } = await import('../src/install.js');
+    await install();
+  } else {
+    await import('../src/index.js');
+  }
+} catch (error) {
+  console.error(`\n  Error: ${error.message}\n`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@lamalibre/install-portlama-e2e-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Portlama E2E test infrastructure — VM lifecycle, snapshots, test execution",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Code Lama Software",
+  "main": "src/index.js",
+  "bin": {
+    "install-portlama-e2e-mcp": "./bin/install-portlama-e2e-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "build": "echo 'No build step for e2e-mcp'"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.3.0",
+    "execa": "^9.6.1",
+    "listr2": "^8.0.0",
+    "zod": "^3.23.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lamalibre/portlama.git",
+    "directory": "packages/install-portlama-e2e-mcp"
+  },
+  "homepage": "https://github.com/lamalibre/portlama#readme",
+  "bugs": {
+    "url": "https://github.com/lamalibre/portlama/issues"
+  },
+  "keywords": [
+    "portlama",
+    "e2e",
+    "mcp",
+    "testing",
+    "multipass",
+    "model-context-protocol"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,60 @@
+// ============================================================================
+// E2E MCP — Configuration & Constants
+// ============================================================================
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Root of the portlama repository. */
+export const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+/** E2E test directories. */
+export const SINGLE_VM_DIR = path.join(REPO_ROOT, 'tests', 'e2e');
+export const THREE_VM_DIR = path.join(REPO_ROOT, 'tests', 'e2e-three-vm');
+export const E2E_LOGS_DIR = path.join(REPO_ROOT, 'e2e-logs');
+
+/** Temp directory for intermediate run data. */
+export const TEMP_DIR = '/tmp/portlama-e2e';
+
+/** VM names. */
+export const VM_HOST = 'portlama-host';
+export const VM_AGENT = 'portlama-agent';
+export const VM_VISITOR = 'portlama-visitor';
+export const ALL_VMS = [VM_HOST, VM_AGENT, VM_VISITOR];
+
+/** Default test domain. */
+export const TEST_DOMAIN = 'test.portlama.local';
+
+/** VM short-name → full multipass name mapping. */
+export const VM_NAME_MAP = { host: VM_HOST, agent: VM_AGENT, visitor: VM_VISITOR };
+
+/** VM profiles — resource allocation tiers. */
+export const PROFILES = {
+  production: {
+    description: 'Matches $4 DigitalOcean droplet — final publishable runs only',
+    cpus: 1,
+    memory: '512M',
+    disk: '10G',
+  },
+  development: {
+    description: 'Fast iteration — logic correctness, comfortable resources',
+    cpus: 2,
+    memory: '2G',
+    disk: '10G',
+  },
+  performance: {
+    description: 'Heavy lifting — parallel tests, fast builds',
+    cpus: 4,
+    memory: '4G',
+    disk: '20G',
+  },
+};
+
+/** Snapshot checkpoints — named save-points in the VM lifecycle. */
+export const CHECKPOINTS = {
+  'post-create': 'VMs exist but no setup has run',
+  'post-setup': 'All VMs provisioned, onboarding complete, services running',
+};

package/src/index.js

@@ -0,0 +1,96 @@
+// ============================================================================
+// Portlama E2E MCP Server
+// ============================================================================
+// MCP server for managing the E2E test infrastructure: VM lifecycle, snapshots,
+// provisioning, test execution with dependency resolution, and two-tier logging.
+//
+// Usage:
+//   node src/index.js              # stdio transport (for Claude Code)
+//   e2e-mcp                        # via bin link
+//
+// Tools:
+//   env_detect          — detect hardware, recommend VM profile
+//   vm_create           — create VMs with a resource profile
+//   vm_list             — list running VMs
+//   vm_delete           — tear down VMs
+//   vm_exec             — execute command on a VM
+//   snapshot_create     — snapshot VMs at a checkpoint
+//   snapshot_restore    — restore VMs to a checkpoint
+//   snapshot_list       — list available snapshots
+//   provision_host      — full host provisioning pipeline
+//   provision_agent     — agent setup with cert transfer
+//   provision_visitor   — visitor setup
+//   hot_reload          — re-pack and redeploy a single package
+//   test_run            — run a specific test with dependency resolution
+//   test_run_all        — run full test suite
+//   test_list           — list tests with dependency graph
+//   test_reset          — reset state between tests
+//   test_publish        — full production run with markdown logs
+//   env_status          — full environment health check
+//   test_log            — fetch raw log for a test run
+// ============================================================================
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { envDetectTool } from './tools/env.js';
+import { vmCreateTool, vmListTool, vmDeleteTool, vmExecTool } from './tools/vm.js';
+import {
+  snapshotCreateTool,
+  snapshotRestoreTool,
+  snapshotListTool,
+} from './tools/snapshots.js';
+import {
+  provisionHostTool,
+  provisionAgentTool,
+  provisionVisitorTool,
+  hotReloadTool,
+} from './tools/provision.js';
+import {
+  testRunTool,
+  testRunAllTool,
+  testListTool,
+  testResetTool,
+  testPublishTool,
+} from './tools/tests.js';
+import { envStatusTool, testLogTool } from './tools/status.js';
+
+const server = new McpServer({
+  name: 'portlama-e2e',
+  version: '0.1.0',
+});
+
+// Register all tools
+const tools = [
+  envDetectTool,
+  vmCreateTool,
+  vmListTool,
+  vmDeleteTool,
+  vmExecTool,
+  snapshotCreateTool,
+  snapshotRestoreTool,
+  snapshotListTool,
+  provisionHostTool,
+  provisionAgentTool,
+  provisionVisitorTool,
+  hotReloadTool,
+  testRunTool,
+  testRunAllTool,
+  testListTool,
+  testResetTool,
+  testPublishTool,
+  envStatusTool,
+  testLogTool,
+];
+
+for (const tool of tools) {
+  // MCP SDK expects raw Zod shape ({ key: z.string() }), not z.object({ ... })
+  const shape = tool.inputSchema.shape || {};
+  server.tool(tool.name, tool.description, shape, async (args) => {
+    return tool.handler(args || {});
+  });
+}
+
+// Start
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/install.js

@@ -0,0 +1,262 @@
+// ============================================================================
+// Interactive Installer
+// ============================================================================
+// Detects the portlama repo, checks prerequisites, and configures Claude Code
+// to use the e2e-mcp server via `claude mcp add`.
+//
+// Usage: npx @lamalibre/install-portlama-e2e-mcp
+//
+// Steps:
+//   1. Detect portlama repository root
+//   2. Verify prerequisites (multipass, node >= 20, claude CLI)
+//   3. Install npm dependencies
+//   4. Verify MCP server loads
+//   5. Register MCP server via `claude mcp add`
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { Listr } from 'listr2';
+import { execa } from 'execa';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Find portlama repo root by walking up from cwd or package location. */
+function findRepoRoot() {
+  // First try: walk up from cwd
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (
+      fs.existsSync(path.join(dir, 'CLAUDE.md')) &&
+      fs.existsSync(path.join(dir, 'packages', 'panel-server'))
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  // Second try: relative to this package (when installed in the monorepo)
+  const candidate = path.resolve(__dirname, '..', '..', '..');
+  if (
+    fs.existsSync(path.join(candidate, 'CLAUDE.md')) &&
+    fs.existsSync(path.join(candidate, 'packages', 'panel-server'))
+  ) {
+    return candidate;
+  }
+
+  return null;
+}
+
+export async function install() {
+  console.log('');
+  console.log(
+    chalk.bold.cyan(
+      '  ┌─────────────────────────────────────────────┐',
+    ),
+  );
+  console.log(
+    chalk.bold.cyan(
+      '  │     Portlama E2E MCP Server Installer       │',
+    ),
+  );
+  console.log(
+    chalk.bold.cyan(
+      '  └─────────────────────────────────────────────┘',
+    ),
+  );
+  console.log('');
+
+  const ctx = {
+    repoRoot: null,
+    serverPath: null,
+    multipassVersion: null,
+    nodeVersion: null,
+    claudeVersion: null,
+  };
+
+  const tasks = new Listr(
+    [
+      {
+        title: 'Detecting portlama repository',
+        task: async (_ctx, task) => {
+          ctx.repoRoot = findRepoRoot();
+          if (!ctx.repoRoot) {
+            throw new Error(
+              'Could not find portlama repository. Run this from within the repo, ' +
+                'or clone it first: git clone https://github.com/lamalibre/portlama.git',
+            );
+          }
+          ctx.serverPath = path.join(
+            ctx.repoRoot,
+            'packages',
+            'install-portlama-e2e-mcp',
+            'src',
+            'index.js',
+          );
+          task.output = ctx.repoRoot;
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Checking Node.js version',
+        task: async (_ctx, task) => {
+          const version = process.version;
+          const major = parseInt(version.slice(1).split('.')[0], 10);
+          if (major < 20) {
+            throw new Error(
+              `Node.js >= 20 required (found ${version}). Install via nvm or nodejs.org.`,
+            );
+          }
+          ctx.nodeVersion = version;
+          task.output = version;
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Checking Multipass installation',
+        task: async (_ctx, task) => {
+          try {
+            const { stdout } = await execa('multipass', ['version']);
+            ctx.multipassVersion = stdout.split('\n')[0];
+            task.output = ctx.multipassVersion;
+          } catch {
+            throw new Error(
+              'Multipass is not installed. Install it from https://multipass.run',
+            );
+          }
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Checking Claude Code CLI',
+        task: async (_ctx, task) => {
+          try {
+            const { stdout } = await execa('claude', ['--version']);
+            ctx.claudeVersion = stdout.trim();
+            task.output = ctx.claudeVersion;
+          } catch {
+            throw new Error(
+              'Claude Code CLI not found. Install it from https://claude.com/claude-code',
+            );
+          }
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Installing dependencies',
+        task: async (_ctx, task) => {
+          const e2eMcpDir = path.join(
+            ctx.repoRoot,
+            'packages',
+            'install-portlama-e2e-mcp',
+          );
+          if (!fs.existsSync(e2eMcpDir)) {
+            throw new Error(
+              `e2e-mcp package not found at ${e2eMcpDir}. ` +
+                'Make sure you have the latest version of the repo.',
+            );
+          }
+
+          // Check if node_modules already exists
+          if (
+            fs.existsSync(path.join(e2eMcpDir, 'node_modules')) ||
+            fs.existsSync(path.join(ctx.repoRoot, 'node_modules'))
+          ) {
+            task.output = 'Already installed (workspace)';
+            return;
+          }
+
+          task.output = 'Running npm install...';
+          await execa('npm', ['install'], { cwd: ctx.repoRoot });
+          task.output = 'Done';
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Verifying MCP server loads',
+        task: async (_ctx, task) => {
+          const configPath = path.join(
+            ctx.repoRoot,
+            'packages',
+            'install-portlama-e2e-mcp',
+            'src',
+            'config.js',
+          );
+          await execa('node', [
+            '-e',
+            `import('${configPath.replace(/\\/g, '\\\\')}').then(() => console.log('OK'))`,
+          ]);
+          task.output = 'Server modules load correctly';
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Registering MCP server with Claude Code',
+        task: async (_ctx, task) => {
+          // Remove existing server if present (idempotent reinstall)
+          await execa('claude', ['mcp', 'remove', 'e2e'], {
+            reject: false,
+          });
+
+          // Register via claude mcp add
+          await execa('claude', [
+            'mcp', 'add',
+            '--transport', 'stdio',
+            'e2e',
+            '--',
+            'node', ctx.serverPath,
+          ]);
+
+          task.output = 'Registered as "e2e" MCP server';
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+    ],
+    {
+      renderer: 'default',
+      rendererOptions: { collapseSubtasks: false },
+      exitOnError: true,
+    },
+  );
+
+  try {
+    await tasks.run();
+
+    console.log('');
+    console.log(chalk.green.bold('  Installation complete!'));
+    console.log('');
+    console.log(
+      chalk.dim('  The following tools are now available in Claude Code:'),
+    );
+    console.log('');
+    console.log('  ' + chalk.cyan('env_detect') + '          — detect hardware, recommend VM profile');
+    console.log('  ' + chalk.cyan('vm_create') + '           — create VMs with resource profile');
+    console.log('  ' + chalk.cyan('vm_list') + '             — list running VMs');
+    console.log('  ' + chalk.cyan('vm_delete') + '           — tear down VMs');
+    console.log('  ' + chalk.cyan('vm_exec') + '             — execute command on a VM');
+    console.log('  ' + chalk.cyan('snapshot_create') + '     — snapshot VMs at checkpoint');
+    console.log('  ' + chalk.cyan('snapshot_restore') + '    — restore VMs to checkpoint');
+    console.log('  ' + chalk.cyan('snapshot_list') + '       — list available snapshots');
+    console.log('  ' + chalk.cyan('provision_host') + '      — full host provisioning');
+    console.log('  ' + chalk.cyan('provision_agent') + '     — agent setup with cert transfer');
+    console.log('  ' + chalk.cyan('provision_visitor') + '   — visitor setup');
+    console.log('  ' + chalk.cyan('hot_reload') + '          — re-deploy a single package');
+    console.log('  ' + chalk.cyan('test_run') + '            — run a test with dependency resolution');
+    console.log('  ' + chalk.cyan('test_run_all') + '        — run full test suite');
+    console.log('  ' + chalk.cyan('test_list') + '           — list tests with dependency graph');
+    console.log('  ' + chalk.cyan('test_reset') + '          — reset state between tests');
+    console.log('  ' + chalk.cyan('test_publish') + '        — production run with markdown logs');
+    console.log('  ' + chalk.cyan('env_status') + '          — environment health check');
+    console.log('  ' + chalk.cyan('test_log') + '            — fetch raw log for debugging');
+    console.log('');
+    console.log(chalk.dim('  Restart Claude Code to activate the MCP server.'));
+    console.log('');
+  } catch (err) {
+    console.log('');
+    console.error(chalk.red(`  Installation failed: ${err.message}`));
+    console.log('');
+    process.exit(1);
+  }
+}

package/src/lib/deps.js

@@ -0,0 +1,162 @@
+// ============================================================================
+// Test Discovery & Dependency Graph
+// ============================================================================
+// Discovers test files from the filesystem and verifies they are git-tracked.
+// Only files matching the NN-name.sh convention that are committed to git are
+// eligible for execution — this prevents injected scripts from being run.
+
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+import { SINGLE_VM_DIR, THREE_VM_DIR, REPO_ROOT } from '../config.js';
+
+/** Pattern for valid test files: two-digit prefix, hyphen, name, .sh extension. */
+const TEST_FILE_PATTERN = /^(\d{2})-[a-z0-9-]+\.sh$/;
+
+/**
+ * Get the set of git-tracked files in a directory (relative to repo root).
+ * Returns a Set of filenames (not full paths).
+ */
+function getGitTrackedFiles(dir) {
+  try {
+    const relativePath = dir.replace(REPO_ROOT + '/', '');
+    const output = execSync(`git ls-files "${relativePath}"`, {
+      cwd: REPO_ROOT,
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
+    return new Set(
+      output
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map((f) => f.split('/').pop()),
+    );
+  } catch {
+    // If git is unavailable, fall back to empty set (all files rejected)
+    return new Set();
+  }
+}
+
+/**
+ * Discover test files from a directory.
+ * Only returns files that:
+ *   1. Match the NN-name.sh naming convention
+ *   2. Are tracked by git (not injected/untracked)
+ * Returns a map of { number: filename }.
+ */
+export function discoverTests(dir) {
+  const gitTracked = getGitTrackedFiles(dir);
+  const files = fs.readdirSync(dir).filter((f) => TEST_FILE_PATTERN.test(f));
+  const map = {};
+
+  for (const file of files) {
+    if (!gitTracked.has(file)) continue; // reject untracked files
+    const num = parseInt(file.slice(0, 2), 10);
+    map[num] = file;
+  }
+
+  return map;
+}
+
+/**
+ * Single-VM test dependency graph.
+ * Key = test number, Value = array of prerequisite test numbers.
+ *
+ * Test 01 verifies fresh install, 03 runs onboarding. Most tests require
+ * onboarding to be complete, so they depend on 03.
+ */
+export const SINGLE_VM_DEPS = {
+  1: [], // fresh-install — no deps
+  2: [1], // mtls-enforcement
+  3: [1], // onboarding-flow
+  4: [3], // tunnel-lifecycle (needs onboarding)
+  5: [3], // user-lifecycle
+  6: [1], // service-control
+  7: [3], // cert-renewal
+  8: [3], // mtls-rotation
+  9: [3], // ip-fallback
+  10: [1], // resilience
+  11: [3], // input-validation
+  12: [3], // user-invitations
+  13: [3], // site-lifecycle
+  14: [3], // shell-lifecycle
+  15: [3], // plugin-lifecycle
+  16: [3], // enrollment-tokens
+};
+
+/**
+ * Three-VM test dependency graph.
+ * All tests require onboarding to be complete (test 01 verifies it).
+ * Tests are otherwise independent — each cleans up after itself.
+ */
+export const THREE_VM_DEPS = {
+  1: [], // onboarding-complete — no deps
+  2: [1], // tunnel-traffic
+  3: [1], // tunnel-toggle-traffic
+  4: [1], // authelia-auth
+  5: [1], // admin-journey
+  6: [1], // tunnel-user-journey
+  7: [1], // site-visitor-journey
+  8: [1], // invitation-journey
+  9: [1], // agent-site-deploy
+  10: [1], // shell-lifecycle
+  11: [1], // plugin-lifecycle
+  12: [1], // enrollment-lifecycle
+};
+
+/** Lazily discovered test maps — cached after first call. */
+let _singleVmTests = null;
+let _threeVmTests = null;
+
+/** Get the single-VM test file map. Auto-discovered and cached. */
+export function getSingleVmTests() {
+  if (!_singleVmTests) _singleVmTests = discoverTests(SINGLE_VM_DIR);
+  return _singleVmTests;
+}
+
+/** Get the three-VM test file map. Auto-discovered and cached. */
+export function getThreeVmTests() {
+  if (!_threeVmTests) _threeVmTests = discoverTests(THREE_VM_DIR);
+  return _threeVmTests;
+}
+
+/** Invalidate cached test maps (e.g. after adding new tests). */
+export function clearTestCache() {
+  _singleVmTests = null;
+  _threeVmTests = null;
+}
+
+/**
+ * Resolve the full dependency chain for a given test number.
+ * Returns a sorted array of test numbers that must run (including the target).
+ */
+export function resolveDeps(testNumber, depGraph) {
+  const visited = new Set();
+  const order = [];
+
+  function walk(n) {
+    if (visited.has(n)) return;
+    visited.add(n);
+    const deps = depGraph[n] || [];
+    for (const dep of deps) {
+      walk(dep);
+    }
+    order.push(n);
+  }
+
+  walk(testNumber);
+  return order.sort((a, b) => a - b);
+}
+
+/**
+ * Given a target test, return the minimal set of test filenames to run.
+ */
+export function resolveTestChain(testNumber, suite = 'three-vm') {
+  const depGraph = suite === 'single-vm' ? SINGLE_VM_DEPS : THREE_VM_DEPS;
+  const testMap = suite === 'single-vm' ? getSingleVmTests() : getThreeVmTests();
+
+  const chain = resolveDeps(testNumber, depGraph);
+  return chain
+    .map((n) => ({ number: n, file: testMap[n] }))
+    .filter((t) => t.file);
+}