@termix-ssh/plugin-sdk 1.0.0

package/dist/testing/setup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared vitest setup for core and for every plugin suite.
+ *
+ * The root vitest.setup.ts re-exports this so there is one copy of the
+ * polyfills rather than two that drift apart.
+ */
+export {};

package/dist/testing/setup.js

@@ -0,0 +1,146 @@
+/**
+ * Shared vitest setup for core and for every plugin suite.
+ *
+ * The root vitest.setup.ts re-exports this so there is one copy of the
+ * polyfills rather than two that drift apart.
+ */
+import { afterEach, vi } from "vitest";
+import { installSafePorts } from "./safe-ports.js";
+installSafePorts();
+if (typeof window !== "undefined" && !window.matchMedia) {
+    window.matchMedia = vi.fn().mockImplementation((query) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+    }));
+}
+/**
+ * jsdom in this project ships without a `localStorage` global, and Node only
+ * provides one when started with --localstorage-file (which persists to disk
+ * and is shared across test files -- both wrong for tests). Suites that touch
+ * storage therefore threw `Cannot read properties of undefined`, taking out
+ * every test in the file rather than just the ones that used it.
+ *
+ * A per-process in-memory implementation is enough: it satisfies the Storage
+ * interface the app uses and keeps nothing on disk.
+ */
+if (typeof globalThis.localStorage === "undefined") {
+    const createMemoryStorage = () => {
+        const store = new Map();
+        return {
+            get length() {
+                return store.size;
+            },
+            key: (index) => Array.from(store.keys())[index] ?? null,
+            getItem: (key) => (store.has(key) ? store.get(key) : null),
+            setItem: (key, value) => {
+                store.set(key, String(value));
+            },
+            removeItem: (key) => {
+                store.delete(key);
+            },
+            clear: () => {
+                store.clear();
+            },
+        };
+    };
+    Object.defineProperty(globalThis, "localStorage", {
+        value: createMemoryStorage(),
+        configurable: true,
+        writable: true,
+    });
+    Object.defineProperty(globalThis, "sessionStorage", {
+        value: createMemoryStorage(),
+        configurable: true,
+        writable: true,
+    });
+}
+/**
+ * A plain plugin host for components a test renders on its own: keys come
+ * back as text, every permission is held, and nothing reaches a server.
+ * renderWithApp installs Termix's real host instead, which takes precedence.
+ */
+const noop = () => { };
+const offline = () => Promise.reject(new Error("No plugin API in a unit test; mock it"));
+globalThis.__termixTestPluginHost = {
+    usePluginId: () => "test-plugin",
+    useTranslation: () => ({
+        t: (key) => key,
+        language: "en",
+    }),
+    usePermission: () => true,
+    useSettings: () => ({ values: {}, loaded: true, save: async () => { } }),
+    useHost: () => null,
+    useHosts: () => ({ hosts: [], loaded: true }),
+    useHostStatus: () => null,
+    useCurrentUser: () => null,
+    useTheme: () => ({ theme: "dark" }),
+    toast: { success: noop, error: noop, info: noop, warning: noop },
+    getApi: () => ({
+        get: offline,
+        delete: offline,
+        post: offline,
+        put: offline,
+        patch: offline,
+    }),
+    useTabs: () => ({
+        openTab: noop,
+        openSingletonTab: noop,
+        connectHost: noop,
+        closeTab: noop,
+        getLayout: () => null,
+        applyLayout: async () => ({ skipped: [] }),
+        onChange: () => noop,
+        onReady: () => noop,
+    }),
+    invokeAction: async () => undefined,
+    useSshAuthTypes: () => ({
+        types: ["password", "key", "credential", "agent", "none"].map((type) => ({
+            type,
+            labelKey: type,
+            pluginId: "core",
+            credentialType: type === "password" || type === "key",
+            supportsBackground: type !== "none",
+            quickConnect: true,
+        })),
+        loaded: true,
+    }),
+    useSlotContributions: () => [],
+    usePluginComponent: () => undefined,
+    getApiFor: () => ({
+        get: offline,
+        delete: offline,
+        post: offline,
+        put: offline,
+        patch: offline,
+    }),
+    hostProtocols: () => ["ssh"],
+    useHostActions: () => [],
+    useActivityTypes: () => [],
+    activityTarget: () => undefined,
+    useExtensions: () => [],
+    getExtension: () => undefined,
+    usePluginUiPreferences: () => ({ values: {}, set: noop }),
+    core: {
+        logActivity: async () => { },
+        getHostPassword: async () => null,
+        patchOpenTab: async () => { },
+        getCustomKeybindings: async () => [],
+        runKeybindingAction: () => false,
+        getClientPreference: () => undefined,
+        setClientPreference: () => { },
+        listHosts: async () => [],
+        listCredentials: async () => [],
+        notifyHostsChanged: () => { },
+        getHostStatusColorScheme: () => "accent",
+        getLocalAuthToken: () => null,
+    },
+};
+afterEach(() => {
+    vi.restoreAllMocks();
+});

package/dist/testing.d.ts

@@ -0,0 +1,537 @@
+/**
+ * Test helpers for plugin authors.
+ *
+ * createMockCtx is the one to reach for: it enforces capabilities the way the
+ * real runtime does. createFakeContext stays for tests that only need a
+ * context-shaped object and do not care about the gates.
+ *
+ * The vitest config these run under comes from @termix-ssh/plugin-sdk/vitest-preset.
+ */
+import type { PluginContext } from "./backend.js";
+import type { HostActionContribution, TermixApp } from "./frontend.js";
+import type { PluginManifest } from "./manifest.js";
+import type { PluginTableDefinition } from "./db.js";
+import type { PluginRouterOptions, PluginWebSocketHandler, PluginWebSockets, PluginWebSocketOptions } from "./backend.js";
+/** A ctx.ws registration as the test doubles record it. */
+export interface FakeWsRoute {
+    path: string;
+    raw: boolean;
+    /** For ctx.ws.route. */
+    handler?: PluginWebSocketHandler;
+    /** For ctx.ws.upgrade. */
+    upgrade?: Parameters<PluginWebSockets["upgrade"]>[1];
+    options?: PluginWebSocketOptions;
+}
+import type { PluginLoginMethod, PluginVerifiedIdentity, PluginSecondFactor, PluginSshAuthProvider, PluginSshConnectOptions, PluginSshHost, PluginHostSummary, PluginShareableUser, PluginShareableRole, PluginSshKeyCredential, PluginSshKeyCredentialInput } from "./backend.js";
+import type { SyncEntityRegistration } from "./backend.js";
+import type { PluginDatabase } from "./backend.js";
+import type { PluginExternalClientRequest, PluginProtocolTarget, PluginHostStatusEntry, PluginNotification, PluginNotificationChannel, PluginNotifyHub, PluginFetchInit, PluginBinarySpec, PluginTlsCertificateInfo, PluginTlsStatus, PluginSummary, PluginKeyboardInteractiveHandler, PluginProcessHandle, PluginProcessOptions } from "./backend.js";
+/** A timer registered through ctx.schedule, run by hand with runScheduled. */
+export interface FakeScheduledJob {
+    kind: "every" | "after";
+    ms: number;
+    fn: () => void | Promise<void>;
+    stopped: boolean;
+}
+export interface FakeContextOptions {
+    pluginId?: string;
+    manifest?: Partial<PluginManifest>;
+    /** Acting user returned by currentActor and used by asUser. */
+    actor?: string;
+    /** Seed for admin-scope ctx.settings. */
+    settings?: Record<string, unknown>;
+    /** Seed for the core settings ctx.settings.readCore can reach. */
+    coreSettings?: Record<string, string>;
+    /** What ctx.ssh.connect and withConnection hand back as the client. */
+    sshClient?: unknown;
+    /** A real database behind ctx.db, usually createTestDb().database. */
+    db?: PluginDatabase;
+    /** What ctx.http.router returns, e.g. () => express.Router(). */
+    router?: () => unknown;
+    /**
+     * Role permissions the acting user holds, as full ids or this plugin's
+     * short names. When set, ctx.rbac enforces them and require() answers 403;
+     * when omitted every check passes, so tests that do not care stay simple.
+     */
+    permissions?: string[];
+    /**
+     * Services other plugins provide, for testing a consumer. Keyed by service
+     * name, or "<service>#<provider>" for a named provider.
+     */
+    services?: Record<string, object>;
+    /** Hosts ctx.hosts.list/get/checkAccess answer with. */
+    hosts?: PluginHostSummary[];
+    /** Users and roles ctx.hosts.listUsers/listRoles answer with. */
+    shareableUsers?: PluginShareableUser[];
+    shareableRoles?: PluginShareableRole[];
+    /** Hosts ctx.ssh.resolveHost answers with, secrets included. */
+    sshHosts?: PluginSshHost[];
+    /**
+     * What ctx.credentials.resolveHostProtocol answers, keyed
+     * "<hostId>:<protocol>". A missing key answers null.
+     */
+    protocolTargets?: Record<string, PluginProtocolTarget>;
+    /** What ctx.credentials.listSshKeys answers. */
+    sshKeyCredentials?: PluginSshKeyCredential[];
+    /** What ctx.desktop.available() answers. Defaults to false. */
+    desktopAvailable?: boolean;
+    /** What ctx.hosts.status.get and check answer, by host id. */
+    hostStatuses?: Record<number, PluginHostStatusEntry>;
+    /** The acting user's channels, what ctx.notify.channels answers. */
+    notificationChannels?: PluginNotificationChannel[];
+    /**
+     * Answers ctx.fetch. Without it every fetch rejects, so a test never
+     * reaches the network by accident.
+     */
+    fetch?: (url: string, init?: PluginFetchInit) => Promise<Response>;
+    /**
+     * Answers ctx.process. Without run every ctx.process.run rejects; without
+     * ensureBinary it answers "/tmp/<pluginId>/bin/<name>".
+     */
+    process?: FakeProcessOptions;
+    /**
+     * What ctx.system.tlsStatus answers before any write. renewal is filled in
+     * from registerTlsRenewer calls.
+     */
+    tlsStatus?: Omit<PluginTlsStatus, "renewal">;
+    /** What ctx.plugins.list answers. Default: only this plugin, active. */
+    installedPlugins?: PluginSummary[];
+    /**
+     * Checks a ctx.system.writeTlsCertificate call. Throw to reject the pair.
+     * Without it every pair is accepted and described with placeholder info.
+     */
+    validateTls?: (certificatePem: string, privateKeyPem: string) => PluginTlsCertificateInfo;
+    /**
+     * Makes ctx.auth.recordEnrollment refuse the way core's policy does (trusted
+     * proxy login on, password login off), with this message and a 409.
+     */
+    refuseEnrollment?: string;
+    /** What ctx.http.baseUrl answers. Defaults to "https://termix.test". */
+    baseUrl?: string;
+    /** What ctx.auth.countLinkedUsers answers, by provider. Defaults to 0. */
+    linkedUsers?: Record<string, number>;
+    /** Failures before ctx.auth.loginRateLimit locks a key. Defaults to 5. */
+    loginAttemptLimit?: number;
+}
+export interface FakeProcessOptions {
+    run?: (file: string, args: readonly string[], options?: PluginProcessOptions) => PluginProcessHandle | Promise<PluginProcessHandle>;
+    ensureBinary?: (spec: PluginBinarySpec) => Promise<string>;
+}
+/** A ctx.process handle a test drives by hand. */
+export interface FakeProcess extends PluginProcessHandle {
+    emitStdout: (chunk: string) => void;
+    emitStderr: (chunk: string) => void;
+    exit: (code: number | null, signal?: string | null) => void;
+    killed: string[];
+}
+export declare function createFakeProcess(pid?: number): FakeProcess;
+export interface FakeAuthRegistrations {
+    sshAuthProviders: PluginSshAuthProvider[];
+    keyboardInteractiveHandlers: PluginKeyboardInteractiveHandler[];
+    loginMethods: PluginLoginMethod[];
+    secondFactors: PluginSecondFactor[];
+    /** "<userId>:<factorId>" for every recorded enrolment. */
+    enrollments: Set<string>;
+    /** Secret schemes registered through ctx.credentials.registerSecretResolver. */
+    secretResolvers: Map<string, (userId: string, reference: string) => Promise<string>>;
+    /** Identities handed to ctx.auth.completeRedirectLogin, in order. */
+    completedLogins: Array<{
+        methodId: string;
+        identity: PluginVerifiedIdentity;
+    }>;
+    /** Every ctx.auth.revokeSessions call, in order. */
+    revokedSessions: Array<{
+        providerId?: number | null;
+        sub?: string | null;
+        sid?: string | null;
+    }>;
+    /** Failures recorded through ctx.auth.loginRateLimit, by "<ip>|<key>". */
+    loginFailures: Map<string, number>;
+}
+export interface FakePluginContext {
+    ctx: PluginContext;
+    /** Runs what ctx.settings.onValidate registered, as a settings save would. */
+    validateSettings: (scope: "admin" | "user" | "host", values: Record<string, unknown>, context?: {
+        hostId?: number;
+    }) => Promise<Record<string, string>>;
+    /** Everything the plugin registered through ctx.disposables. */
+    disposals: Array<() => void | Promise<void>>;
+    /** Topics emitted through ctx.events.emit, in order. */
+    emitted: Array<{
+        topic: string;
+        payload: unknown;
+    }>;
+    /** Backing store behind ctx.kv. */
+    kv: Map<string, unknown>;
+    /** Table definitions registered through ctx.db.define, in order. */
+    tables: PluginTableDefinition[];
+    /** Sync entities registered through ctx.sync.registerEntity, in order. */
+    syncEntities: SyncEntityRegistration[];
+    /**
+     * WebSocket routes registered through ctx.ws, in order, with the handler
+     * and options, so a test can hand a route a fake socket.
+     */
+    wsRoutes: FakeWsRoute[];
+    /** Router options passed to ctx.http.router, in order. */
+    httpRouters: Array<PluginRouterOptions | undefined>;
+    /** Backing store behind ctx.settings, keyed "<scope>:<scopeId>:<key>". */
+    settings: Map<string, unknown>;
+    /** Core settings readable through ctx.settings.readCore. */
+    coreSettings: Map<string, string>;
+    /** Every ctx.ssh.connect and withConnection call, in order. */
+    sshConnections: Array<{
+        host: number | PluginSshHost;
+        pool?: string;
+        options?: PluginSshConnectOptions;
+    }>;
+    /** Every ctx.hosts.share call, in order. */
+    hostShares: Array<{
+        hostId: number;
+        targets: unknown[];
+        permissionLevel: string;
+        durationHours?: number;
+    }>;
+    /** Everything registered through ctx.auth. */
+    auth: FakeAuthRegistrations;
+    /** Every ctx.desktop.openIsolatedWindow call, in order. */
+    desktopWindows: Array<{
+        url: string;
+        partition?: string;
+        title?: string;
+        ignoreCert?: boolean;
+    }>;
+    /** Every ctx.desktop.launchExternalClient call, in order. */
+    externalClientLaunches: PluginExternalClientRequest[];
+    /** Every ctx.credentials.resolveHostProtocol call, in order. */
+    credentialReads: Array<{
+        hostId: number;
+        protocol: string;
+    }>;
+    /** Every ctx.credentials.createSshKey call, with the id it answered. */
+    createdSshKeys: Array<PluginSshKeyCredentialInput & {
+        id: number;
+    }>;
+    /** Every ctx.notify.send call, with the actor it ran as. */
+    notifications: Array<{
+        actor: string | undefined;
+        notification: PluginNotification;
+    }>;
+    /** The hub the plugin registered with ctx.notify.serve, if any. */
+    notifyHub: {
+        current: PluginNotifyHub | null;
+    };
+    /** Backing store behind ctx.secrets.get/set, keyed "<userId>:<key>". */
+    secretStore: Map<string, string>;
+    /** Every ctx.fetch call, in order. */
+    fetches: Array<{
+        url: string;
+        init?: PluginFetchInit;
+    }>;
+    /** Every ctx.process.run call, in order. */
+    processRuns: Array<{
+        file: string;
+        args: readonly string[];
+        options?: PluginProcessOptions;
+    }>;
+    /** Every ctx.process.ensureBinary call, in order. */
+    binaries: PluginBinarySpec[];
+    /** What ctx.system did: accepted writes, reloads, live challenges and renewers. */
+    tls: {
+        writes: Array<{
+            certificatePem: string;
+            privateKeyPem: string;
+        }>;
+        reloads: number;
+        /** ctx.system calls by name, in order. */
+        calls: string[];
+        challenges: Map<string, string>;
+        renewers: number;
+    };
+    /** Every ctx.audit.record entry, in order. */
+    audits: Array<{
+        action: string;
+        success: boolean;
+        [key: string]: unknown;
+    }>;
+    /** Every ctx.hosts.recordActivity call, in order. */
+    activities: Array<{
+        hostId: number;
+        type: string;
+        hostName: string;
+    }>;
+    /** Host ids with a live ctx.hosts.trackSession, one entry per session. */
+    trackedSessions: number[];
+    /** Every ctx.ssh.startInteraction / cancelInteraction call, in order. */
+    interactions: Array<{
+        action: "start" | "cancel";
+        interaction: string;
+        request: Record<string, unknown>;
+    }>;
+    /** Every ctx.hosts.status.reportLogin call, in order. */
+    statusReports: Array<{
+        hostId: number;
+        ok: boolean;
+        hostKeyChanged?: boolean;
+    }>;
+    /** ctx.hosts.status.registerPort resolvers, by connection type. */
+    statusPorts: Map<string, (hostId: number) => unknown>;
+    /** Backing store behind ctx.hosts.status.get and check. */
+    hostStatuses: Map<number, PluginHostStatusEntry>;
+    /** Every ctx.ssh.dropPooled call, in order. */
+    droppedPools: Array<{
+        pool: string;
+        hostId: number;
+    }>;
+    /** Every ctx.schedule timer, stopped ones included. */
+    scheduled: FakeScheduledJob[];
+    /** Runs every live ctx.schedule job once; "after" jobs are then done. */
+    runScheduled: () => Promise<void>;
+    /** Changes the acting user, as core's request middleware would. */
+    setActor: (userId: string | undefined) => void;
+    /**
+     * Runs `fn` as `userId`, the way a request from that user would. For test
+     * code standing in for a caller; unlike ctx.asUser it needs no capability.
+     */
+    actAs: <T>(userId: string, fn: () => Promise<T> | T) => Promise<T>;
+    /** Provided or seeded services, by name or "<service>#<provider>". */
+    services: Map<string, object>;
+}
+/**
+ * A context double good enough to call activate() against in a unit test.
+ * Nothing here is capability-checked: a test asserting a capability gate
+ * should use the real runtime, not this.
+ */
+export declare function createFakeContext(options?: FakeContextOptions): FakePluginContext;
+export interface MockContextOptions {
+    pluginId?: string;
+    manifest?: Partial<PluginManifest>;
+    /** Capabilities the plugin is granted. Anything else throws. */
+    capabilities?: string[];
+    /** Seed for ctx.kv. */
+    kv?: Record<string, unknown>;
+    /** Seed for this plugin's own admin-scope settings. */
+    settings?: Record<string, unknown>;
+    /** Seed for the core settings readCore can reach. */
+    coreSettings?: Record<string, string>;
+    /** Acting user returned by currentActor and used by asUser. */
+    actor?: string;
+    /** What ctx.ssh.connect and withConnection hand back as the client. */
+    sshClient?: unknown;
+    /** A real database behind ctx.db, usually createTestDb().database. */
+    db?: PluginDatabase;
+    /** What ctx.http.router returns, e.g. () => express.Router(). */
+    router?: () => unknown;
+    /** Role permissions the acting user holds. See FakeContextOptions. */
+    permissions?: string[];
+    /** Hosts ctx.hosts.list/get/checkAccess serve. See FakeContextOptions. */
+    hosts?: PluginHostSummary[];
+    /** Users and roles ctx.hosts.listUsers/listRoles serve. See FakeContextOptions. */
+    shareableUsers?: PluginShareableUser[];
+    shareableRoles?: PluginShareableRole[];
+    /** Other plugins' services. See FakeContextOptions. */
+    services?: Record<string, object>;
+    /** Hosts ctx.ssh.resolveHost serves. See FakeContextOptions. */
+    sshHosts?: PluginSshHost[];
+    /** What ctx.credentials serves. See FakeContextOptions. */
+    protocolTargets?: Record<string, PluginProtocolTarget>;
+    /** What ctx.credentials.listSshKeys serves. */
+    sshKeyCredentials?: PluginSshKeyCredential[];
+    /** What ctx.desktop.available() answers. */
+    desktopAvailable?: boolean;
+    /** What ctx.hosts.status answers. See FakeContextOptions. */
+    hostStatuses?: Record<number, PluginHostStatusEntry>;
+    /** The acting user's channels, what ctx.notify.channels answers. */
+    notificationChannels?: PluginNotificationChannel[];
+    /**
+     * Answers ctx.fetch. Without it every fetch rejects, so a test never
+     * reaches the network by accident.
+     */
+    fetch?: (url: string, init?: PluginFetchInit) => Promise<Response>;
+    /** See FakeContextOptions. */
+    process?: FakeProcessOptions;
+    /** See FakeContextOptions. */
+    tlsStatus?: FakeContextOptions["tlsStatus"];
+    /** See FakeContextOptions. */
+    installedPlugins?: FakeContextOptions["installedPlugins"];
+    /** See FakeContextOptions. */
+    validateTls?: FakeContextOptions["validateTls"];
+    /** See FakeContextOptions. */
+    refuseEnrollment?: string;
+    /** See FakeContextOptions. */
+    baseUrl?: string;
+    /** See FakeContextOptions. */
+    linkedUsers?: Record<string, number>;
+    /** See FakeContextOptions. */
+    loginAttemptLimit?: number;
+}
+export interface MockPluginContext extends FakePluginContext {
+    /** Capability ids checked during the test, in order, denied ones included. */
+    checked: string[];
+}
+/**
+ * A context double that gates on capabilities the way src/backend/plugins/ctx.ts
+ * does, so a test can prove a plugin fails closed without a running server.
+ *
+ * The gates on today's ctx surface: kv:own on every ctx.kv call, db:own on
+ * ctx.db, network:serve on ctx.http and ctx.ws, events:core on emitting a
+ * topic outside the plugin's own namespace, settings:read-core on
+ * ctx.settings.readCore, ssh:connect plus credentials:use on ctx.ssh,
+ * notify:send on ctx.notify (notify:hub on serve), network:outbound on ctx.fetch, process:spawn on
+ * ctx.process, system:tls on ctx.system, plugins:read on ctx.plugins, and auth:provide on ctx.auth. Reading a plugin's own settings is deliberately
+ * ungated. As the SDK grows a member, add its gate here in the same shape.
+ */
+export declare function createMockCtx(options?: MockContextOptions): MockPluginContext;
+/** A sqlite handle as createTestDb exposes it. Structural, like better-sqlite3's. */
+export interface TestSqlite {
+    exec: (sql: string) => unknown;
+    prepare: (sql: string) => {
+        run: (...params: unknown[]) => unknown;
+        get: (...params: unknown[]) => unknown;
+        all: (...params: unknown[]) => unknown[];
+    };
+    close: () => void;
+}
+export interface TestDbOptions {
+    /**
+     * Runs after the core stub tables exist and before the plugin's migrations,
+     * e.g. to create the legacy table an adoption migration renames.
+     */
+    before?: (sqlite: TestSqlite) => unknown;
+    /** Skip applying the migrations, to apply them by hand later. */
+    skipMigrations?: boolean;
+}
+export interface TestDb {
+    /** The raw better-sqlite3 handle, for asserting on tables directly. */
+    sqlite: TestSqlite;
+    /** The Drizzle handle ctx.db.client() returns. */
+    drizzle: unknown;
+    /** Pass this as createMockCtx({ db }). */
+    database: PluginDatabase;
+    /** How many times ctx.db.persist() was called. */
+    readonly persisted: number;
+    /** The migration ids applied, in order. */
+    applied: string[];
+    /** Applies the plugin's sqlite migrations, when skipMigrations was set. */
+    migrate: () => Promise<string[]>;
+    close: () => void;
+}
+/**
+ * An in-memory SQLite database with a plugin's own migrations applied.
+ *
+ * Core's users, ssh_data, roles and user_roles exist as minimal stubs with
+ * foreign keys on, so a refUser or refHost column cascades exactly as it
+ * does on the server, and ctx.db.refs() has something real to join against.
+ * The migrations are read from <pluginDir>/migrations/sqlite and split with
+ * the same splitter the server's runner uses.
+ */
+export declare function createTestDb(pluginDir: string, options?: TestDbOptions): Promise<TestDb>;
+/**
+ * Rendering a plugin frontend in a test.
+ *
+ * renderWithApp activates the plugin against the real registration surface,
+ * so a test sees exactly what the shell would: which rail items, tabs, host
+ * actions and cards it registered, and each of those rendered with the SDK
+ * hooks working. It is implemented by the Termix host, which is where the
+ * registries live; the vitest preset points "@termix-ssh/plugin-host/testing" at
+ * core's implementation.
+ */
+export interface RenderWithAppOptions {
+    pluginId?: string;
+    manifest?: Partial<PluginManifest>;
+    /** Role permissions the current user holds. */
+    permissions?: string[];
+    isAdmin?: boolean;
+    /** Hosts useHosts() returns. */
+    hosts?: Array<Record<string, unknown>>;
+    /** The plugin's locales/en.json, loaded into its namespace. */
+    locales?: Record<string, unknown>;
+    /** Render as an anonymous guest page. */
+    guest?: boolean;
+    /** What app.tabs.getLayout returns until the plugin applies another. */
+    layout?: import("./frontend.js").ShellLayout;
+    /** Fire app.tabs.onReady after activation, as the shell does after login. */
+    ready?: boolean;
+    /** Stands in for app.api and usePluginApi(), e.g. a stub of the routes. */
+    api?: import("./frontend.js").PluginApiClient;
+    /** What app.desktop.remoteServerUrl() answers. Read on every call. */
+    remoteServerUrl?: () => string | null | Promise<string | null>;
+}
+/** A call a plugin made on the shell, recorded instead of performed. */
+export interface ShellCall {
+    method: string;
+    args: unknown[];
+}
+export interface RenderedPluginApp {
+    app: TermixApp;
+    /** Everything this plugin registered, by kind. */
+    registered: {
+        railItems: () => Array<{
+            id: string;
+            hidden?: boolean;
+            /** The full permission id the item is gated on, if any. */
+            permission?: string;
+        }>;
+        tabs: () => string[];
+        panels: () => string[];
+        hostActions: () => Array<{
+            id: string;
+            tabType?: string;
+        }>;
+        /** This plugin's host actions that apply to `host`, as the shell sees them. */
+        hostActionsFor: (host: unknown) => HostActionContribution[];
+        hostProtocols: () => string[];
+        hostEditorSections: () => string[];
+        dashboardCards: () => string[];
+        /** Ids this plugin added to an extension point. */
+        extensions: (pointId: string) => string[];
+        settingsComponents: () => string[];
+        slot: (slotId: string) => string[];
+        actions: () => string[];
+        loginMethods: () => string[];
+        secondFactors: () => string[];
+        paletteGroups: () => string[];
+        keybindingActions: () => string[];
+        keybindingDefaults: () => string[];
+    };
+    /** A registered palette group's items, as the palette loads them on open. */
+    loadPaletteGroup: (id: string) => Promise<import("./frontend.js").PaletteItem[]>;
+    /** Shell calls made by the plugin's code, applyLayout included. */
+    shellCalls: ShellCall[];
+    /**
+     * Tabs the last app.tabs.applyLayout opened, under the shell's own restore
+     * rules: a tab whose host is gone is skipped, a tab no running plugin
+     * registered is kept.
+     */
+    openedTabs: () => Array<{
+        type: string;
+        hostId?: number;
+        label: string;
+    }>;
+    /**
+     * Renders an opened tab the way the shell would, which for a tab no running
+     * plugin registered is the "needs the plugin" placeholder.
+     */
+    renderOpenedTab: (index: number) => HTMLElement;
+    renderTab: (type: string, props?: Record<string, unknown>) => HTMLElement;
+    renderPanel: (id: string, props?: Record<string, unknown>) => HTMLElement;
+    renderDashboardCard: (id: string) => HTMLElement;
+    /** Renders one component of a contributed extension, "view" by default. */
+    renderExtension: (pointId: string, id: string, component?: string, props?: Record<string, unknown>) => HTMLElement;
+    renderHostEditorSection: (id: string, props?: Record<string, unknown>) => HTMLElement;
+    renderSettingsComponent: (componentId: string, props?: Record<string, unknown>) => HTMLElement;
+    /** Renders a login method's UI with login screen props, overridable. */
+    renderLoginMethod: (id: string, props?: Record<string, unknown>) => HTMLElement;
+    /** Renders a second factor's challenge with overridable props. */
+    renderSecondFactor: (id: string, props?: Record<string, unknown>) => HTMLElement;
+    /** Renders the Settings > Security section a factor or method brought. */
+    renderEnrollment: (id: string) => HTMLElement;
+    /** Renders a slot the way its owner would. */
+    renderSlot: (slotId: string, props?: Record<string, unknown>) => HTMLElement;
+    /** Runs deactivate and every disposer, as disabling the plugin does. */
+    deactivate: () => Promise<void>;
+}
+export type FrontendPluginModule = {
+    activate: (app: TermixApp) => void | Promise<void>;
+    deactivate?: () => void | Promise<void>;
+};
+export declare function renderWithApp(plugin: FrontendPluginModule, options?: RenderWithAppOptions): Promise<RenderedPluginApp>;