@thefehr/foundry-playwright 0.2.1

package/README.md

@@ -0,0 +1,79 @@
+# @thefehr/foundry-playwright
+
+A robust, multi-version E2E testing library for FoundryVTT modules and systems, powered by Playwright.
+
+## Status
+
+This repository is currently in the **Extraction & Initialization** phase. Detailed documentation can be found in the `docs/` directory.
+
+## Documentation
+
+### Architecture & Design
+
+- [Authentication & World Selection](docs/architecture/auth-and-world.md)
+- [State Manipulation Fixtures](docs/architecture/state-manipulation.md)
+- [Canvas Interaction Utilities](docs/architecture/canvas-interaction.md)
+- [System Agnosticism & Configuration](docs/architecture/system-agnosticism.md)
+- [Multi-Version Support (V13 & V14)](docs/architecture/multi-version-support.md)
+- [Docker Test Orchestrator for Developers](docs/architecture/docker-orchestrator.md)
+
+### Plans & RFCs
+
+- [RFC 0001: Main Extraction Plan](docs/rfcs/0001-extraction-plan.md)
+- [Extraction & Integration Strategy](docs/rfcs/extraction-strategy.md)
+- [Continuous Verification & Release Tracking](docs/rfcs/continuous-verification.md)
+- [Roadmap: Features & Helper Functions](docs/rfcs/roadmap-and-features.md)
+
+## Core Features
+
+- **Multi-Version Support:** Built-in adapters for FoundryVTT V13 and V14.
+- **Docker Orchestration:** Automated setup and teardown of version-specific Foundry instances via CLI or programmatic orchestrator.
+- **State Manipulation:** Fast, UI-less data injection via direct Foundry API and socket calls (`createActor`, `updateDocument`, `grantCurrency`).
+- **UI Helpers:** Robust tab switching, aggressive tour suppression, and dialog automation.
+
+## Getting Started
+
+### Quick Start (Initialization)
+
+The easiest way to get started is by using the CLI to bootstrap your project:
+
+```bash
+# Install the library
+npm install --save-dev @thefehr/foundry-playwright
+
+# Initialize the test suite
+npx foundry-playwright init
+```
+
+This will create a `playwright.config.ts`, an `e2e` directory with a sample test, and add a `test:e2e` script to your `package.json`.
+
+### Writing Your First Test
+
+Use the `useFoundry` helper to handle the complex authentication and world setup:
+
+```typescript
+import { test, expect, useFoundry } from "@thefehr/foundry-playwright";
+
+// Automatically boots Foundry and sets up the environment
+useFoundry(test, {
+  worldId: "test-world",
+  systemId: "dnd5e",
+  moduleId: "my-module-id",
+});
+
+test("Foundry is ready", async ({ page }) => {
+  await page.goto("/");
+  await expect(page).toHaveTitle(/Foundry VTT/);
+});
+```
+
+### Running Tests
+
+```bash
+# Run tests with a Docker-orchestrated Foundry instance
+npm run test:e2e
+```
+
+For more detailed instructions, see the [Migration Guide](docs/getting-started/migration-guide.md).
+
+## Core Features

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+import { Page } from "@playwright/test";
+/**
+ * Navigates from within a world or the join screen back to the setup screen.
+ * Implements RFC 0008 transition logic.
+ */
+export declare function returnToSetup(page: Page, adminPassword?: string, _version?: string | number): Promise<void>;
+/**
+ * Performs full end-to-end setup of a Foundry VTT instance.
+ */
+export declare function foundrySetup(page: Page, config?: any): Promise<void>;
+/**
+ * Performs teardown of a Foundry VTT world.
+ */
+export declare function foundryTeardown(page: Page, config: any): Promise<void>;
+/**
+ * Logs into a Foundry VTT world as a specific user.
+ */
+export declare function loginAs(page: Page, userName: string, password?: string): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,287 @@
+import { disableTour, waitForReady, validateStack } from "./helpers.js";
+import { getSetupAdapter } from "./setup/index.js";
+/**
+ * Navigates from within a world or the join screen back to the setup screen.
+ * Implements RFC 0008 transition logic.
+ */
+export async function returnToSetup(page, adminPassword, _version) {
+    console.log("[returnToSetup] Returning to setup screen...");
+    let maxAttempts = 3;
+    for (let i = 0; i < maxAttempts; i++) {
+        const url = page.url();
+        console.log(`[returnToSetup] Attempt ${i + 1}. Current URL: ${url}`);
+        if (url.includes("/setup")) {
+            // Check if we are actually on setup or just redirected to setup login
+            const setupPwInput = page.locator('input[name="adminPassword"]');
+            if (await setupPwInput.isVisible()) {
+                console.log("[returnToSetup] Admin login required on /setup.");
+                await setupPwInput.fill(adminPassword || process.env.FOUNDRY_ADMIN_PASSWORD || "password");
+                await page
+                    .locator('button[type="submit"], button:has-text("Log In")')
+                    .first()
+                    .evaluate((el) => el.click());
+                await page
+                    .waitForURL((u) => u.pathname.includes("/setup"), { timeout: 10000 })
+                    .catch(() => null);
+                await page.waitForLoadState("networkidle");
+            }
+            // Definitively check for setup application root
+            const isSetup = await page.evaluate(() => !!document.querySelector("foundry-app#setup") ||
+                document.body.classList.contains("setup"));
+            if (isSetup) {
+                console.log("[returnToSetup] Successfully reached Setup screen.");
+                return;
+            }
+        }
+        if (url.includes("/auth")) {
+            console.log("[returnToSetup] On /auth screen. Logging in...");
+            const pwInput = page.locator('input[name="adminPassword"]');
+            if (await pwInput.isVisible()) {
+                await pwInput.fill(adminPassword || process.env.FOUNDRY_ADMIN_PASSWORD || "password");
+                await page
+                    .locator('button[type="submit"], button:has-text("Log In")')
+                    .first()
+                    .evaluate((el) => el.click());
+                // Wait for setup root OR url change
+                await Promise.race([
+                    page.waitForURL((u) => u.pathname.includes("/setup"), { timeout: 20000 }),
+                    page.waitForSelector("foundry-app#setup, body.setup", { timeout: 20000 }),
+                ]).catch(() => null);
+                await page.waitForLoadState("networkidle");
+            }
+            continue;
+        }
+        if (url.includes("/join")) {
+            console.log("[returnToSetup] On /join screen. Attempting Shutdown...");
+            // Check for V14 admin-gated shutdown form
+            const shutdownForm = page.locator("#join-game-setup");
+            const shutdownInput = shutdownForm.locator('input[name="adminPassword"]');
+            if (await shutdownInput.isVisible()) {
+                console.log("[returnToSetup] V14 Shutdown form detected. Filling password...");
+                await shutdownInput.fill(adminPassword || process.env.FOUNDRY_ADMIN_PASSWORD || "password");
+                await shutdownForm
+                    .locator('button[type="submit"]')
+                    .first()
+                    .evaluate((el) => el.click());
+                await page.waitForTimeout(5000); // Allow time for shutdown
+            }
+            else {
+                // Standard return or direct navigation
+                const returnBtn = page.locator('button:has-text("Return to Setup"), button[name="shutdown"]');
+                if (await returnBtn.isVisible()) {
+                    await returnBtn.evaluate((el) => el.click());
+                }
+                else {
+                    await page.goto("/setup").catch(() => null);
+                }
+            }
+            await page.waitForLoadState("networkidle");
+            continue;
+        }
+        if (url.includes("/game") || url.includes("/players")) {
+            console.log("[returnToSetup] Inside World. Attempting to logout/shutdown...");
+            await page
+                .evaluate(() => {
+                // @ts-ignore
+                if (typeof game !== "undefined" && game.shutDown)
+                    game.shutDown();
+                else
+                    window.location.href = "/setup";
+            })
+                .catch(() => null);
+            await page.waitForTimeout(3000);
+            await page.waitForLoadState("networkidle");
+            continue;
+        }
+        // Default: try direct jump
+        console.log(`[returnToSetup] Navigating to /setup...`);
+        await page.goto("/setup").catch(() => null);
+        await page.waitForLoadState("networkidle");
+    }
+}
+/**
+ * Performs full end-to-end setup of a Foundry VTT instance.
+ */
+export async function foundrySetup(page, config = {}) {
+    const SYSTEM_LABELS = {
+        dnd5e: "D&D 5th Edition",
+        pf2e: "Pathfinder 2e",
+        pf1: "Pathfinder 1st Edition",
+        swade: "Savage Worlds Adventure Edition",
+        worldbuilding: "Simple Worldbuilding",
+        dungeonworld: "Dungeon World",
+    };
+    const { worldId, systemId = process.env.FOUNDRY_SYSTEM_ID || "dnd5e", systemManifest, moduleId, moduleManifest, adminPassword = process.env.FOUNDRY_ADMIN_PASSWORD || process.env.FOUNDRY_ADMIN_KEY, userName = "Gamemaster", password = "", createWorld = true, deleteIfExists = true, version = process.env.FOUNDRY_VERSION, } = config;
+    const systemLabel = config.systemLabel || SYSTEM_LABELS[systemId] || systemId;
+    console.log(`[foundrySetup] Starting setup for world: ${worldId} (System: ${systemId})`);
+    let done = false;
+    let maxAttempts = 5;
+    for (let attempt = 1; attempt <= maxAttempts && !done; attempt++) {
+        if (page.url() === "about:blank")
+            await page.goto("/");
+        await disableTour(page);
+        await page.waitForLoadState("networkidle");
+        const url = page.url();
+        // 0. World Lock check
+        if (url.includes("/join") || url.includes("/game") || url.includes("/players")) {
+            await returnToSetup(page, adminPassword, version);
+            continue;
+        }
+        // 1. License Screen
+        if (url.endsWith("/license") || url.includes("/license#")) {
+            const adapter = await getSetupAdapter(page, version);
+            await adapter.handleEULA(page);
+            continue;
+        }
+        // 2. Admin Auth Screen
+        if (url.endsWith("/auth") ||
+            url.includes("/auth#") ||
+            (url.includes("/setup") && (await page.locator('input[name="adminPassword"]').isVisible()))) {
+            console.log("[foundrySetup] Admin login required.");
+            const pwInput = page.locator('input[name="adminPassword"]');
+            if (await pwInput.isVisible()) {
+                await pwInput.fill(adminPassword);
+                await page
+                    .locator('button[type="submit"], button:has-text("Log In")')
+                    .first()
+                    .evaluate((el) => el.click());
+                await page
+                    .waitForURL((u) => u.pathname.includes("/setup"), { timeout: 15000 })
+                    .catch(() => null);
+                await page.waitForLoadState("networkidle");
+            }
+            continue;
+        }
+        // 3. Setup Screen
+        if (url.endsWith("/setup") || url.includes("/setup#")) {
+            console.log("[foundrySetup] On setup screen. Proceeding with configuration...");
+            const adapter = await getSetupAdapter(page, version);
+            // Aggressively clear Usage Data/Sharing dialogs (Shadow DOM included)
+            await page.evaluate(() => {
+                document.querySelectorAll("dialog, .application, foundry-app").forEach((d) => {
+                    const text = d.textContent?.toLowerCase() || "";
+                    if ((text.includes("usage data") || text.includes("sharing")) &&
+                        !text.includes("license")) {
+                        if (d.tagName.toLowerCase() === "dialog")
+                            d.close?.();
+                        d.remove();
+                    }
+                });
+            });
+            // MANDATORY ORDER: Install system FIRST so Worlds tab is enabled in V14
+            if (systemManifest) {
+                await adapter.installSystemFromManifest(page, systemManifest);
+            }
+            else if (systemId) {
+                await adapter.installSystem(page, systemId, systemLabel);
+            }
+            // 4. Module Installation
+            if (moduleManifest) {
+                await adapter.installModuleFromManifest(page, moduleManifest);
+            }
+            else if (moduleId) {
+                const moduleIds = Array.isArray(moduleId) ? moduleId : [moduleId];
+                await adapter.installModules(page, moduleIds);
+            }
+            // 5. World Management (NOW SAFE in V14 as system exists)
+            if (deleteIfExists)
+                await adapter.deleteWorldIfExists(page, worldId);
+            if (createWorld) {
+                await adapter.createWorld(page, worldId, systemLabel, systemId);
+                // Final redirection check
+                if (page.url().includes("/game") ||
+                    page.url().includes("/join") ||
+                    page.url().includes("/players")) {
+                    done = true;
+                }
+                else {
+                    console.log(`[foundrySetup] Manually launching world "${worldId}"...`);
+                    await adapter.switchTab(page, "Worlds");
+                    const worldBox = page
+                        .locator(`[data-package-id="${worldId}"], [data-module-id="${worldId}"]`)
+                        .first();
+                    const launchBtn = worldBox
+                        .locator('[data-action="worldLaunch"], button:has-text("Launch")')
+                        .first();
+                    await launchBtn.evaluate((el) => el.click());
+                    done = true;
+                }
+            }
+            else {
+                done = true;
+            }
+        }
+    }
+    if (!done)
+        throw new Error(`Failed to reach setup or game screen after ${maxAttempts} attempts.`);
+    // 6. Final Join and Game Ready
+    await page.waitForURL((u) => u.pathname.includes("/join") ||
+        u.pathname.includes("/game") ||
+        u.pathname.includes("/players"), { timeout: 60000 });
+    if (page.url().includes("/join")) {
+        console.log(`[foundrySetup] On join screen. Logging in as "${userName}"...`);
+        await page.locator('select[name="userid"]').selectOption({ label: userName });
+        if (password)
+            await page.locator('input[name="password"]').fill(password);
+        await page
+            .locator('button[name="join"]')
+            .evaluate((el) => el.click());
+        await page.waitForURL(/\/game/, { timeout: 60000 });
+    }
+    console.log("[foundrySetup] Waiting for game to be ready...");
+    await waitForReady(page);
+    // RFC 0008: Validate the stack against the registry
+    await validateStack(page, version).catch(() => null);
+    // 7. Module Activation via Server-Side Settings (RFC 0008 strategy)
+    if (moduleId) {
+        const moduleIds = Array.isArray(moduleId) ? moduleId : [moduleId];
+        console.log(`[foundrySetup] Activating modules via server settings: ${moduleIds.join(", ")}`);
+        await page.evaluate(async (ids) => {
+            // @ts-ignore
+            const current = game.settings.get("core", "moduleConfiguration") || {};
+            let changed = false;
+            ids.forEach((id) => {
+                if (!current[id]) {
+                    current[id] = true;
+                    changed = true;
+                }
+            });
+            if (changed) {
+                // @ts-ignore
+                await game.settings.set("core", "moduleConfiguration", current);
+                // @ts-ignore
+                game.socket.emit("reload");
+                window.location.reload();
+            }
+        }, moduleIds);
+        await page.waitForLoadState("networkidle");
+        await waitForReady(page);
+    }
+}
+/**
+ * Performs teardown of a Foundry VTT world.
+ */
+export async function foundryTeardown(page, config) {
+    const { worldId, adminPassword = process.env.FOUNDRY_ADMIN_PASSWORD || process.env.FOUNDRY_ADMIN_KEY, version = process.env.FOUNDRY_VERSION, } = config;
+    console.log("[foundryTeardown] Starting teardown...");
+    await returnToSetup(page, adminPassword, version).catch(() => null);
+    await page.waitForLoadState("networkidle");
+    const adapter = await getSetupAdapter(page, version);
+    await disableTour(page);
+    await adapter.deleteWorldIfExists(page, worldId);
+    console.log("[foundryTeardown] Teardown complete.");
+}
+/**
+ * Logs into a Foundry VTT world as a specific user.
+ */
+export async function loginAs(page, userName, password) {
+    if (!page.url().includes("/join"))
+        await page.goto("/join");
+    await page.waitForLoadState("networkidle");
+    await page.locator('select[name="userid"]').selectOption({ label: userName });
+    if (password)
+        await page.locator('input[name="password"]').fill(password);
+    await page.locator('button[name="join"]').evaluate((el) => el.click());
+    await page.waitForURL(/\/game/, { timeout: 60000 });
+    await waitForReady(page);
+}

package/dist/canvas.d.ts

@@ -0,0 +1,47 @@
+import { Page } from "@playwright/test";
+/**
+ * Utilities for interacting with the Foundry VTT WebGL Canvas.
+ */
+export declare class FoundryCanvas {
+    private page;
+    constructor(page: Page);
+    /**
+     * Converts grid coordinates (row, col) to viewport pixels.
+     * @param x The grid X coordinate (column).
+     * @param y The grid Y coordinate (row).
+     */
+    gridToPixels(x: number, y: number): Promise<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Clicks on a specific token by its ID.
+     * @param tokenId The ID of the token.
+     */
+    clickToken(tokenId: string): Promise<void>;
+    /**
+     * Double-clicks on a specific token by its ID (usually opens sheet).
+     * @param tokenId The ID of the token.
+     */
+    doubleClickToken(tokenId: string): Promise<void>;
+    /**
+     * Drags a token from its current position to a target grid coordinate.
+     * @param tokenId The ID of the token to drag.
+     * @param targetX The target grid X coordinate.
+     * @param targetY The target grid Y coordinate.
+     */
+    dragToken(tokenId: string, targetX: number, targetY: number): Promise<void>;
+    /**
+     * Right-clicks on the canvas at a specific grid coordinate.
+     */
+    rightClickGrid(x: number, y: number): Promise<void>;
+    /**
+     * Targets a token (simulates the 'T' key).
+     * @param tokenId The ID of the token to target.
+     */
+    targetToken(tokenId: string): Promise<void>;
+    /**
+     * Internal helper to get the viewport pixels for a token's center.
+     */
+    private getTokenCanvasPosition;
+}

package/dist/canvas.js

@@ -0,0 +1,105 @@
+/**
+ * Utilities for interacting with the Foundry VTT WebGL Canvas.
+ */
+export class FoundryCanvas {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    /**
+     * Converts grid coordinates (row, col) to viewport pixels.
+     * @param x The grid X coordinate (column).
+     * @param y The grid Y coordinate (row).
+     */
+    async gridToPixels(x, y) {
+        return this.page.evaluate(({ x, y }) => {
+            // @ts-ignore
+            const canvas = window.canvas;
+            if (!canvas || !canvas.ready)
+                throw new Error("Canvas is not ready.");
+            // Calculate pixels using Foundry's coordinate system
+            // Note: This accounts for padding and scale
+            const pixels = canvas.grid.getTopLeft(x, y);
+            const center = canvas.grid.getCenter(pixels[0], pixels[1]);
+            // Convert canvas coordinates to global (viewport) pixels
+            const global = canvas.stage.worldTransform.apply({ x: center[0], y: center[1] });
+            // Account for the canvas element's position on the page
+            const rect = document.getElementById("canvas")?.getBoundingClientRect();
+            if (!rect)
+                throw new Error("Canvas element not found.");
+            return {
+                x: global.x + rect.left,
+                y: global.y + rect.top,
+            };
+        }, { x, y });
+    }
+    /**
+     * Clicks on a specific token by its ID.
+     * @param tokenId The ID of the token.
+     */
+    async clickToken(tokenId) {
+        const coords = await this.getTokenCanvasPosition(tokenId);
+        await this.page.mouse.click(coords.x, coords.y);
+    }
+    /**
+     * Double-clicks on a specific token by its ID (usually opens sheet).
+     * @param tokenId The ID of the token.
+     */
+    async doubleClickToken(tokenId) {
+        const coords = await this.getTokenCanvasPosition(tokenId);
+        await this.page.mouse.click(coords.x, coords.y, { clickCount: 2 });
+    }
+    /**
+     * Drags a token from its current position to a target grid coordinate.
+     * @param tokenId The ID of the token to drag.
+     * @param targetX The target grid X coordinate.
+     * @param targetY The target grid Y coordinate.
+     */
+    async dragToken(tokenId, targetX, targetY) {
+        const start = await this.getTokenCanvasPosition(tokenId);
+        const end = await this.gridToPixels(targetX, targetY);
+        await this.page.mouse.move(start.x, start.y);
+        await this.page.mouse.down();
+        await this.page.mouse.move(end.x, end.y, { steps: 10 });
+        await this.page.mouse.up();
+    }
+    /**
+     * Right-clicks on the canvas at a specific grid coordinate.
+     */
+    async rightClickGrid(x, y) {
+        const coords = await this.gridToPixels(x, y);
+        await this.page.mouse.click(coords.x, coords.y, { button: "right" });
+    }
+    /**
+     * Targets a token (simulates the 'T' key).
+     * @param tokenId The ID of the token to target.
+     */
+    async targetToken(tokenId) {
+        const coords = await this.getTokenCanvasPosition(tokenId);
+        await this.page.mouse.move(coords.x, coords.y);
+        await this.page.keyboard.press("t");
+    }
+    /**
+     * Internal helper to get the viewport pixels for a token's center.
+     */
+    async getTokenCanvasPosition(tokenId) {
+        return this.page.evaluate((id) => {
+            // @ts-ignore
+            const token = window.canvas.tokens.get(id);
+            if (!token)
+                throw new Error(`Token ${id} not found on canvas.`);
+            // Get center in canvas coordinates
+            const center = token.center;
+            // Convert to global pixels
+            // @ts-ignore
+            const global = window.canvas.stage.worldTransform.apply(center);
+            const rect = document.getElementById("canvas")?.getBoundingClientRect();
+            if (!rect)
+                throw new Error("Canvas element not found.");
+            return {
+                x: global.x + rect.left,
+                y: global.y + rect.top,
+            };
+        }, tokenId);
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { DockerFoundryOrchestrator } from "../docker.js";
+import { initAction } from "./init.js";
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+const program = new Command();
+program
+    .name("foundry-playwright")
+    .description("CLI for Foundry VTT E2E testing with Playwright")
+    .version("0.1.0");
+program.command("init").description("Initialize a new Foundry E2E test project").action(initAction);
+program
+    .command("test")
+    .description("Run E2E tests with an optional Docker-orchestrated Foundry instance")
+    .option("-v, --version <version>", "Foundry VTT version", process.env.FOUNDRY_VERSION || "13")
+    .option("-s, --system <id>", "System ID", process.env.FOUNDRY_SYSTEM_ID || "dnd5e")
+    .option("--docker", "Use Docker for the Foundry instance")
+    .option("--update-registry", "Update verified-versions.json on success")
+    .option("--playwright <command>", "Playwright command to run", "npx playwright test")
+    .action(async (options) => {
+    const { version, system, docker, updateRegistry, playwright } = options;
+    let orchestrator = null;
+    try {
+        if (docker) {
+            const tmpDataDir = path.join(process.cwd(), ".foundry_test_data", `.foundry_data_tmp_${Date.now()}`);
+            orchestrator = new DockerFoundryOrchestrator({
+                version,
+                adminKey: process.env.FOUNDRY_ADMIN_KEY || "password",
+                dataDir: tmpDataDir,
+            });
+            // Auto-inject local modules if they exist in e2e/ (common pattern in this repo)
+            const e2ePath = path.join(process.cwd(), "e2e");
+            if (fs.existsSync(e2ePath)) {
+                const items = fs.readdirSync(e2ePath);
+                for (const item of items) {
+                    const itemPath = path.join(e2ePath, item);
+                    if (fs.statSync(itemPath).isDirectory() &&
+                        fs.existsSync(path.join(itemPath, "module.json"))) {
+                        const modulesDir = path.join(tmpDataDir, "Data", "modules", item);
+                        fs.mkdirSync(modulesDir, { recursive: true });
+                        fs.cpSync(itemPath, modulesDir, { recursive: true });
+                    }
+                }
+            }
+            const url = await orchestrator.start();
+            process.env.FOUNDRY_URL = url;
+        }
+        process.env.FOUNDRY_VERSION = version;
+        process.env.FOUNDRY_SYSTEM_ID = system;
+        console.log(`Running: ${playwright}`);
+        execSync(playwright, { stdio: "inherit", env: process.env });
+        if (updateRegistry) {
+            // Logic to update verified-versions.json
+            console.log("Updating registry...");
+            const registryPath = path.join(process.cwd(), "verified-versions.json");
+            if (fs.existsSync(registryPath)) {
+                const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+                registry.pending = registry.pending.filter((v) => v.version !== version);
+                if (!registry.verified.find((v) => v.version === version)) {
+                    registry.verified.push({
+                        version,
+                        timestamp: new Date().toISOString(),
+                        status: "stable",
+                        notes: `Verified with CLI.`,
+                    });
+                }
+                fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+            }
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    finally {
+        if (orchestrator) {
+            await orchestrator.stopAndRemove();
+        }
+    }
+});
+program.parse();

package/dist/cli/init.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Action for the 'init' CLI command.
+ * Bootstraps a new Foundry E2E test project.
+ */
+export declare function initAction(): Promise<void>;