@lamalibre/install-portlama-e2e-mcp 0.1.0

package/src/lib/logs.js

@@ -0,0 +1,146 @@
+// ============================================================================
+// Two-Tier Log Management
+// ============================================================================
+// Tier 1 (intermediate): Structured JSON in TEMP_DIR/runs/<id>/
+//   - summary.json: pass/fail counts, timing, error excerpts
+//   - tests/<name>.json: per-test structured result
+//   - logs/<name>.log: raw output (fetched on demand)
+//
+// Tier 2 (final/publish): Full Markdown in e2e-logs/ (current format)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { TEMP_DIR } from '../config.js';
+
+/** Validate that a path component contains no traversal sequences. */
+function validatePathComponent(value, label) {
+  if (value.includes('/') || value.includes('\\') || value.includes('..')) {
+    throw new Error(`Invalid ${label}: must not contain path separators or ".."`)
+  }
+}
+
+/** Create a new run directory and return its ID and paths. */
+export function createRun() {
+  const id = new Date().toISOString().replace(/[:.]/g, '-');
+  const runDir = path.join(TEMP_DIR, 'runs', id);
+  const testsDir = path.join(runDir, 'tests');
+  const logsDir = path.join(runDir, 'logs');
+
+  fs.mkdirSync(testsDir, { recursive: true });
+  fs.mkdirSync(logsDir, { recursive: true });
+
+  return { id, runDir, testsDir, logsDir };
+}
+
+/** Write a per-test structured result. */
+export function writeTestResult(testsDir, testName, result) {
+  const filePath = path.join(testsDir, `${testName}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(result, null, 2));
+}
+
+/** Write raw log output for a test. */
+export function writeTestLog(logsDir, testName, output) {
+  const filePath = path.join(logsDir, `${testName}.log`);
+  fs.writeFileSync(filePath, output);
+}
+
+/** Write the run summary. */
+export function writeSummary(runDir, summary) {
+  const filePath = path.join(runDir, 'summary.json');
+  fs.writeFileSync(filePath, JSON.stringify(summary, null, 2));
+}
+
+/** Read a run summary. Returns null if not found. */
+export function readSummary(runId) {
+  validatePathComponent(runId, 'runId');
+  const filePath = path.join(TEMP_DIR, 'runs', runId, 'summary.json');
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Read raw log for a specific test in a run. */
+export function readTestLog(runId, testName) {
+  validatePathComponent(runId, 'runId');
+  validatePathComponent(testName, 'testName');
+  const filePath = path.join(TEMP_DIR, 'runs', runId, 'logs', `${testName}.log`);
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/** Read structured result for a specific test in a run. */
+export function readTestResult(runId, testName) {
+  validatePathComponent(runId, 'runId');
+  validatePathComponent(testName, 'testName');
+  const filePath = path.join(TEMP_DIR, 'runs', runId, 'tests', `${testName}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** List all run IDs, most recent first. */
+export function listRuns() {
+  const runsDir = path.join(TEMP_DIR, 'runs');
+  try {
+    return fs.readdirSync(runsDir).sort().reverse();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Parse raw test output to extract error lines.
+ * Looks for [FAIL] markers and assertion failures.
+ */
+export function extractErrors(rawOutput) {
+  const lines = rawOutput.split('\n');
+  const errors = [];
+
+  for (const line of lines) {
+    const stripped = line.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '').trim();
+    if (
+      stripped.includes('[FAIL]') ||
+      stripped.includes('assertion failed') ||
+      stripped.includes('FATAL') ||
+      stripped.includes('returned 500') ||
+      stripped.includes('exit code')
+    ) {
+      errors.push(stripped);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Build a compact summary suitable for MCP tool response.
+ * Only includes errors for failed tests — saves context.
+ */
+export function buildCompactSummary(summary) {
+  const lines = [];
+  lines.push(`Run: ${summary.runId}`);
+  lines.push(`Passed: ${summary.passed}, Failed: ${summary.failed}, Skipped: ${summary.skipped}`);
+  lines.push(`Duration: ${Math.round(summary.durationMs / 1000)}s`);
+
+  if (summary.failed > 0) {
+    lines.push('');
+    lines.push('Failures:');
+    for (const test of summary.tests) {
+      if (test.status === 'failed') {
+        lines.push(`  ${test.name}:`);
+        for (const err of test.errors || []) {
+          lines.push(`    - ${err}`);
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/lib/multipass.js

@@ -0,0 +1,161 @@
+// ============================================================================
+// Multipass CLI wrapper
+// ============================================================================
+// All VM interactions go through this module. Uses execa with array arguments
+// per project convention — no shell interpolation.
+
+import { execa } from 'execa';
+
+/**
+ * Run a multipass command and return { stdout, stderr, exitCode }.
+ * Throws on non-zero exit unless `allowFailure` is set.
+ */
+export async function run(args, { allowFailure = false, timeout = 120_000 } = {}) {
+  try {
+    const result = await execa('multipass', args, { timeout });
+    return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
+  } catch (err) {
+    if (allowFailure) {
+      return {
+        stdout: err.stdout || '',
+        stderr: err.stderr || err.message,
+        exitCode: err.exitCode || 1,
+      };
+    }
+    throw err;
+  }
+}
+
+/** Launch a new VM with the given specs. */
+export async function launch(name, { cpus, memory, disk }) {
+  return run([
+    'launch',
+    '24.04',
+    '--name',
+    name,
+    '--cpus',
+    String(cpus),
+    '--memory',
+    memory,
+    '--disk',
+    disk,
+  ]);
+}
+
+/** Delete a VM and purge all deleted instances. */
+export async function deleteVm(name) {
+  await run(['delete', name], { allowFailure: true });
+  await run(['purge'], { allowFailure: true });
+}
+
+/** Delete a VM without purging (caller handles purge). */
+export async function deleteVmNoPurge(name) {
+  await run(['delete', name], { allowFailure: true });
+}
+
+/** Get info for a VM as JSON. Returns null if VM doesn't exist. */
+export async function info(name) {
+  const result = await run(['info', name, '--format', 'json'], {
+    allowFailure: true,
+  });
+  if (result.exitCode !== 0) return null;
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+/** Get the IPv4 address of a VM. Returns null if unavailable. */
+export async function getIp(name) {
+  const data = await info(name);
+  if (!data?.info?.[name]?.ipv4?.[0]) return null;
+  return data.info[name].ipv4[0];
+}
+
+/** List all VMs. Returns an array of { name, state, ipv4 }. */
+export async function list() {
+  const result = await run(['list', '--format', 'json'], {
+    allowFailure: true,
+  });
+  if (result.exitCode !== 0) return [];
+  try {
+    const data = JSON.parse(result.stdout);
+    return (data.list || []).map((vm) => ({
+      name: vm.name,
+      state: vm.state,
+      ipv4: vm.ipv4?.[0] || null,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/** Execute a command on a VM. */
+export async function exec(
+  vmName,
+  command,
+  { sudo = false, timeout = 120_000, allowFailure = false } = {},
+) {
+  const args = ['exec', vmName, '--'];
+  if (sudo) args.push('sudo');
+
+  // command can be a string or array
+  if (typeof command === 'string') {
+    args.push('bash', '-c', command);
+  } else if (Array.isArray(command)) {
+    args.push(...command);
+  } else {
+    throw new Error(`exec: command must be a string or array, got ${typeof command}: ${JSON.stringify(command)}`);
+  }
+
+  return run(args, { allowFailure, timeout });
+}
+
+/** Transfer a file to a VM. */
+export async function transfer(localPath, vmDest) {
+  return run(['transfer', localPath, vmDest]);
+}
+
+/** Transfer a file from a VM to local. */
+export async function transferFrom(vmSource, localPath) {
+  return run(['transfer', vmSource, localPath]);
+}
+
+/** Create a snapshot of a VM. */
+export async function snapshot(vmName, snapshotName) {
+  return run(['snapshot', vmName, '--name', snapshotName]);
+}
+
+/** Restore a VM to a named snapshot. */
+export async function restore(vmName, snapshotName) {
+  return run(['restore', '--destructive', `${vmName}.${snapshotName}`]);
+}
+
+/** List snapshots for a VM. Returns array of snapshot names. */
+export async function listSnapshots(vmName) {
+  const result = await run(['list', '--snapshots', '--format', 'json'], {
+    allowFailure: true,
+  });
+  if (result.exitCode !== 0) return [];
+  try {
+    const data = JSON.parse(result.stdout);
+    // multipass list --snapshots --format json returns { "info": { "vm-name": { "snap-name": {...} } } }
+    const vmInfo = data?.info?.[vmName];
+    if (!vmInfo || typeof vmInfo !== 'object') return [];
+    return Object.keys(vmInfo);
+  } catch {
+    return [];
+  }
+}
+
+/** Delete a specific snapshot. */
+export async function deleteSnapshot(vmName, snapshotName) {
+  return run(['delete', `${vmName}.${snapshotName}`], { allowFailure: true });
+}
+
+/** Check if multipass is installed and running. */
+export async function isAvailable() {
+  const result = await run(['version'], { allowFailure: true });
+  return result.exitCode === 0;
+}

package/src/lib/profiles.js

@@ -0,0 +1,69 @@
+// ============================================================================
+// VM Profile Selection & Hardware Detection
+// ============================================================================
+
+import os from 'node:os';
+import { PROFILES } from '../config.js';
+
+/** Parse a memory string like "2G" or "512M" into megabytes. */
+function parseMemoryMB(mem) {
+  const match = mem.match(/^(\d+(?:\.\d+)?)\s*([MG])$/i);
+  if (!match) return 0;
+  const value = parseFloat(match[1]);
+  const unit = match[2].toUpperCase();
+  return unit === 'G' ? value * 1024 : value;
+}
+
+/** Detect host hardware capabilities. */
+export function detectHardware() {
+  const cpus = os.cpus().length;
+  const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
+  const freeMemoryGB = os.freemem() / (1024 * 1024 * 1024);
+
+  return {
+    cpus,
+    totalMemoryGB: Math.round(totalMemoryGB * 10) / 10,
+    freeMemoryGB: Math.round(freeMemoryGB * 10) / 10,
+  };
+}
+
+/**
+ * Recommend a VM profile based on available hardware.
+ * Returns { profile, name, supported[], note }.
+ */
+export function recommendProfile(hardware) {
+  const vmCount = 3; // host + agent + visitor
+  const hostReserveGB = 2; // leave for the host OS
+  const availableMemoryGB = hardware.freeMemoryGB - hostReserveGB;
+  const availableCpus = Math.max(1, hardware.cpus - 2);
+
+  const supported = [];
+
+  // Check each profile from most demanding to least
+  for (const [name, profile] of Object.entries(PROFILES).reverse()) {
+    const perVmMB = parseMemoryMB(profile.memory);
+    const totalNeededMB = perVmMB * vmCount;
+    const totalNeededGB = totalNeededMB / 1024;
+    const cpusNeeded = profile.cpus * vmCount;
+
+    if (totalNeededGB <= availableMemoryGB && cpusNeeded <= availableCpus) {
+      supported.push(name);
+    }
+  }
+
+  // production always fits (512M × 3 = 1.5G)
+  if (!supported.includes('production')) {
+    supported.push('production');
+  }
+
+  // Recommend the most capable supported profile
+  const preference = ['performance', 'development', 'production'];
+  const recommended = preference.find((p) => supported.includes(p)) || 'production';
+
+  const profile = PROFILES[recommended];
+  const note =
+    `${vmCount} VMs × ${profile.memory} = ${(parseMemoryMB(profile.memory) * vmCount) / 1024}G` +
+    ` (${Math.round(availableMemoryGB * 10) / 10}G available after ${hostReserveGB}G host reserve)`;
+
+  return { profile, name: recommended, supported, note };
+}

package/src/lib/state.js

@@ -0,0 +1,81 @@
+// ============================================================================
+// State Management
+// ============================================================================
+// Tracks VM state, run history, and snapshot inventory in a JSON file.
+// Written to TEMP_DIR/state.json for intermediate runs.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { TEMP_DIR } from '../config.js';
+
+const STATE_FILE = path.join(TEMP_DIR, 'state.json');
+
+/** Ensure TEMP_DIR exists with owner-only permissions. */
+function ensureTempDir() {
+  if (!fs.existsSync(TEMP_DIR)) {
+    fs.mkdirSync(TEMP_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function defaultState() {
+  return {
+    vms: {},
+    profile: null,
+    domain: null,
+    credentials: null,
+    lastRun: null,
+    runs: [],
+  };
+}
+
+/** Load state from disk. Returns default state if file doesn't exist. */
+export function loadState() {
+  try {
+    const raw = fs.readFileSync(STATE_FILE, 'utf-8');
+    return { ...defaultState(), ...JSON.parse(raw) };
+  } catch {
+    return defaultState();
+  }
+}
+
+/** Persist state to disk with restricted permissions (0o600). */
+export function saveState(state) {
+  ensureTempDir();
+  const tmp = STATE_FILE + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, STATE_FILE);
+}
+
+/** Update a subset of state fields. */
+export function updateState(partial) {
+  const state = loadState();
+  Object.assign(state, partial);
+  saveState(state);
+  return state;
+}
+
+/** Record VM info in state. */
+export function setVmState(name, info) {
+  const state = loadState();
+  state.vms[name] = { ...state.vms[name], ...info, updatedAt: new Date().toISOString() };
+  saveState(state);
+}
+
+/** Remove a VM from state. */
+export function removeVmState(name) {
+  const state = loadState();
+  delete state.vms[name];
+  saveState(state);
+}
+
+/** Record a test run result. */
+export function recordRun(run) {
+  const state = loadState();
+  state.lastRun = run.id;
+  state.runs.push(run);
+  // Keep last 20 runs
+  if (state.runs.length > 20) {
+    state.runs = state.runs.slice(-20);
+  }
+  saveState(state);
+}

package/src/tools/env.js

@@ -0,0 +1,45 @@
+// ============================================================================
+// env_detect — Hardware detection and profile recommendation
+// ============================================================================
+
+import { z } from 'zod';
+import { detectHardware, recommendProfile } from '../lib/profiles.js';
+import { PROFILES } from '../config.js';
+
+export const envDetectTool = {
+  name: 'env_detect',
+  description:
+    'Detect host hardware capabilities and recommend a VM profile. ' +
+    'Returns CPU count, available memory, recommended profile, and all supported profiles. ' +
+    'Run this before vm_create to choose the right resource tier.',
+  inputSchema: z.object({}),
+  async handler() {
+    const hardware = detectHardware();
+    const recommendation = recommendProfile(hardware);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              host: {
+                cpus: hardware.cpus,
+                totalMemoryGB: hardware.totalMemoryGB,
+                freeMemoryGB: hardware.freeMemoryGB,
+              },
+              recommendedProfile: recommendation.name,
+              supportedProfiles: recommendation.supported,
+              profileSpecs: Object.fromEntries(
+                recommendation.supported.map((name) => [name, PROFILES[name]]),
+              ),
+              note: recommendation.note,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  },
+};