appilot-mcp 0.0.1 → 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tool surface of the Appilot MCP server, built as a factory.
+ *
+ * One connection profile in, one McpServer out. The factory shape is what lets
+ * the same tools serve two transports: a local stdio process that carries the
+ * operator's own credentials in its environment, and the remote HTTP service,
+ * where every request arrives with the caller's own service token and therefore
+ * needs its own server instance. Nothing here knows which transport it is under.
+ *
+ * Contract: docs/content-model/config-health-contract.md.
+ * Server:   docs/architecture/appilot-mcp.md.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AppilotConnection } from './config.js';
+export declare function createAppilotServer(conn: AppilotConnection): McpServer;

package/dist/server.js

@@ -0,0 +1,358 @@
+/**
+ * Tool surface of the Appilot MCP server, built as a factory.
+ *
+ * One connection profile in, one McpServer out. The factory shape is what lets
+ * the same tools serve two transports: a local stdio process that carries the
+ * operator's own credentials in its environment, and the remote HTTP service,
+ * where every request arrives with the caller's own service token and therefore
+ * needs its own server instance. Nothing here knows which transport it is under.
+ *
+ * Contract: docs/content-model/config-health-contract.md.
+ * Server:   docs/architecture/appilot-mcp.md.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { AppilotClient } from './client.js';
+import { runHealthContract } from './contract/healthContract.js';
+import { soakSelectors } from './soak.js';
+import { applyManifest, parseManifest, planManifest } from './manifest.js';
+import { scaffoldIntegration } from './scaffold.js';
+import { verifyIntegration } from './verify.js';
+import { redactForTransport } from './redaction.js';
+/**
+ * Where the widget bundle is served from when the caller does not say. Cloud
+ * default; an on-premise instance serves its own copy and passes the URL.
+ */
+const DEFAULT_WIDGET_SCRIPT_URL = 'https://cdn.appilot.space/widget/v1/appilot.esm.js';
+export function createAppilotServer(conn) {
+    const client = new AppilotClient(conn);
+    function text(value) {
+        const body = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+        return { content: [{ type: 'text', text: body }] };
+    }
+    function errorText(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+    function resolveAppId(appId) {
+        const id = appId ?? conn.defaultAppId;
+        if (id == null || !Number.isFinite(id)) {
+            throw new Error('appId is required (pass it, or set APPILOT_APP_ID).');
+        }
+        return id;
+    }
+    function formatReport(report) {
+        if (report.findings.length === 0)
+            return 'No findings. Configuration passes the health contract.';
+        const lines = [
+            `${report.findings.length} finding(s), critical: ${report.counts.critical}, high: ${report.counts.high}, medium: ${report.counts.medium}, low: ${report.counts.low}`,
+            '',
+        ];
+        for (const f of report.findings) {
+            lines.push(`[${f.severity.toUpperCase()}] ${f.category} · ${f.entity}`);
+            lines.push(`  ${f.message}`);
+            if (f.recommendation)
+                lines.push(`  → ${f.recommendation}`);
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    const server = new McpServer({ name: 'appilot-mcp', version: '0.1.0' });
+    server.registerTool('capabilities', {
+        title: 'Discover instance capabilities',
+        description: 'Probe the connected Appilot instance for its version, applied migration level, payload-schema versions, and configurable entities. Call this first so you configure against what THIS instance supports (on-premise instances can trail cloud).',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const [caps, health] = await Promise.all([
+                client.getCapabilities(),
+                client.getHealth().catch(() => null),
+            ]);
+            return text({ baseUrl: conn.baseUrl, health, capabilities: caps });
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('read_config', {
+        title: 'Read app configuration',
+        description: 'Read the content-model configuration (views, controls, forms, action plans, knowledge) for an app and return a normalized snapshot. Use before validating or editing.',
+        inputSchema: { appId: z.number().int().optional(), locales: z.array(z.string()).optional() },
+    }, async ({ appId, locales }) => {
+        try {
+            const snapshot = await client.buildSnapshot(resolveAppId(appId), locales);
+            return text(snapshot);
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('validate_config', {
+        title: 'Validate against the health contract',
+        description: 'Audit an app\'s configuration against the Appilot config health contract: plan actionability (a create flow must enter a value and submit, not just open an element), marker resolution, selector stability (no auto-generated ids), i18n coverage, KB scope/hygiene, and identifier hygiene. Runs locally; also echoes the server-side plan trust boundary. Returns severity-ranked findings.',
+        inputSchema: { appId: z.number().int().optional(), locales: z.array(z.string()).optional() },
+    }, async ({ appId, locales }) => {
+        try {
+            const id = resolveAppId(appId);
+            const snapshot = await client.buildSnapshot(id, locales);
+            const report = runHealthContract(snapshot);
+            // Server-side echo per plan (best-effort; needs a config:write token).
+            for (const plan of snapshot.actionPlans) {
+                try {
+                    const echo = await client.validatePlan(id, plan.sections, plan.form_values);
+                    for (const e of echo.errors) {
+                        report.findings.push({ severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`, message: `[server] ${e}` });
+                    }
+                }
+                catch { /* read-only token or older instance: local gate already ran */ }
+            }
+            return text(formatReport(report) + '\n\n' + JSON.stringify(report.counts));
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('update_action_plan', {
+        title: 'Update an action plan',
+        description: 'Apply a patch to a stored action plan (sections, form_values, name/description/step narratives, is_active). The server re-validates the marker trust boundary and rejects an invalid patch. Requires a config:write service token.',
+        inputSchema: { id: z.string(), patch: z.record(z.any()) },
+    }, async ({ id, patch }) => {
+        try {
+            return text(await client.updateActionPlan(id, patch));
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('update_control', {
+        title: 'Update a control',
+        description: 'Apply a patch to a control (e.g. replace an unstable locator with a stable selector list). Requires a config:write service token.',
+        inputSchema: { id: z.string(), patch: z.record(z.any()) },
+    }, async ({ id, patch }) => {
+        try {
+            return text(await client.updateControl(id, patch));
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('update_knowledge', {
+        title: 'Update a knowledge article',
+        description: 'Apply a patch to a knowledge_content row (e.g. fix scope, add a translation, remove chatbot filler). Requires a config:write service token.',
+        inputSchema: { id: z.string(), patch: z.record(z.any()) },
+    }, async ({ id, patch }) => {
+        try {
+            return text(await client.updateKnowledge(id, patch));
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('export_config', {
+        title: 'Export the app configuration as a portable bundle',
+        description: 'Export the whole content-model configuration (views, controls, forms, tools, zones, action plans, knowledge, session templates) as a canonical, versioned ConfigBundle: the round-trip artifact for backup, clone, and restore. Secrets never travel; the bundle carries secretRefs[] references only, so the file is safe to save or share. Distinct from read_config, which is the reasoning view.',
+        inputSchema: { appId: z.number().int().optional() },
+    }, async ({ appId }) => {
+        try {
+            const bundle = await client.exportConfig(resolveAppId(appId));
+            const header = `contentHash ${bundle.contentHash} · formatVersion ${bundle.formatVersion} · secretRefs ${bundle.secretRefs.length}`;
+            return text(`${header}\n${JSON.stringify(bundle, null, 2)}`);
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('import_config', {
+        title: 'Import a ConfigBundle (merge or replace)',
+        description: 'Import a ConfigBundle into an app. ALWAYS dry-run first (dryRun defaults to true): the dry-run returns the per-entity diff, health findings, and the currentHash confirm token. mode=merge upserts by semantic key and never deletes; mode=replace makes the app match the bundle exactly, INCLUDING deletions, and a replace commit requires expectedCurrentHash from the dry-run (409 CONFIG_STALE_WRITE if the config changed in between). Every commit first persists a pre_restore revision, so a wrong import is undone by restoring it. Requires a config:write service token.',
+        inputSchema: {
+            appId: z.number().int().optional(),
+            bundle: z.union([z.record(z.any()), z.string()]),
+            mode: z.enum(['merge', 'replace']),
+            dryRun: z.boolean().optional(),
+            expectedCurrentHash: z.string().optional(),
+            allowUnhealthy: z.boolean().optional(),
+        },
+    }, async ({ appId, bundle, mode, dryRun, expectedCurrentHash, allowUnhealthy }) => {
+        try {
+            const id = resolveAppId(appId);
+            // Capability negotiation is client-side UX; the server re-validates
+            // regardless. An instance without configPortability predates the
+            // import surface entirely.
+            const caps = await client.getCapabilities();
+            if (!caps.configPortability) {
+                return errorText(new Error('The connected instance does not support config import (no configPortability capability). Upgrade the instance or fall back to per-entity update_* tools.'));
+            }
+            const parsedBundle = typeof bundle === 'string' ? JSON.parse(bundle) : bundle;
+            const bundleVersion = String(parsedBundle.formatVersion ?? '');
+            const supported = caps.configPortability.bundleFormatVersion;
+            const newer = (a, b) => {
+                const [am, an] = a.split('.').map(Number);
+                const [bm, bn] = b.split('.').map(Number);
+                return am > bm || (am === bm && an > bn);
+            };
+            if (bundleVersion && newer(bundleVersion, supported)) {
+                return errorText(new Error(`Bundle format ${bundleVersion} is newer than the instance supports (${supported}). Export from a matching instance or upgrade the target.`));
+            }
+            const result = await client.importConfig(id, {
+                mode,
+                dryRun: dryRun !== false,
+                bundle: parsedBundle,
+                expectedCurrentHash,
+                allowUnhealthy,
+            });
+            return text(result);
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    // -- provisioning ------------------------------------------------------
+    // The path from "I have an account" to "the widget answers on my page".
+    // Everything here needs a service token holding `provision:write`.
+    server.registerTool('whoami', {
+        title: 'Check which org and scopes this credential reaches',
+        description: 'Self-check the connected credential: which organization it reaches, which app it is narrowed to, and which scopes it holds. Call this before any write so a mistyped or revoked token fails here rather than as an opaque 401 mid-task. Returns no secret.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            return text({ baseUrl: conn.baseUrl, ...(await client.whoami()) });
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('create_app', {
+        title: 'Create an app, its domains, and a widget key',
+        description: 'Provision an Appilot app in one call: the app, the domains it runs on, and optionally a widget key, plus the exact script tag and boot snippet to paste into the host application. Idempotent: re-running converges on the existing app rather than creating a second one. Pass dryRun to preview. The widget key and its secret are returned EXACTLY ONCE, at creation; store the secret in the host backend only. Requires a provision:write service token.',
+        inputSchema: {
+            name: z.string().min(1),
+            description: z.string().optional(),
+            domains: z.array(z.string()).optional(),
+            widgetKeyName: z.string().optional(),
+            isTestKey: z.boolean().optional(),
+            dryRun: z.boolean().optional(),
+        },
+    }, async ({ name, description, domains, widgetKeyName, isTestKey, dryRun }) => {
+        try {
+            const result = await client.provisionApp({
+                app: { name, description },
+                domains: (domains ?? []).map(domain => ({ domain })),
+                widgetKey: widgetKeyName || isTestKey !== undefined
+                    ? { name: widgetKeyName, isTest: isTestKey }
+                    : undefined,
+                dryRun: dryRun === true,
+            });
+            return text(redactForTransport(result, conn.transport));
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('plan_manifest', {
+        title: 'Preview an app manifest (writes nothing)',
+        description: 'Diff an appilot.app-manifest against the live instance and return what would change: provisioning actions per app/domain/key, the config-bundle import diff, and the health findings over the resulting state. Writes nothing. Returns a planToken that apply_manifest requires, so an apply always follows a preview of the exact same manifest. Keep the manifest in the repository under version control.',
+        inputSchema: { manifest: z.union([z.record(z.any()), z.string()]) },
+    }, async ({ manifest }) => {
+        try {
+            const parsed = parseManifest(manifest);
+            const plan = await planManifest(client, parsed, id => {
+                const resolved = id ?? conn.defaultAppId;
+                return resolved != null && Number.isFinite(resolved) ? resolved : null;
+            });
+            return text(plan);
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('apply_manifest', {
+        title: 'Apply a previously planned app manifest',
+        description: 'Provision and configure an app from an appilot.app-manifest. Requires the planToken returned by plan_manifest for the SAME manifest: a mismatch means the manifest changed after it was previewed, and the apply is refused. Pass expectedCurrentHash from the plan so a concurrent config edit is a 409 rather than a silent overwrite. mode=replace makes the config match the bundle exactly, including deletions. Requires provision:write, and config:write when the manifest carries a config bundle.',
+        inputSchema: {
+            manifest: z.union([z.record(z.any()), z.string()]),
+            planToken: z.string(),
+            mode: z.enum(['merge', 'replace']).optional(),
+            expectedCurrentHash: z.string().optional(),
+            allowUnhealthy: z.boolean().optional(),
+        },
+    }, async ({ manifest, planToken, mode, expectedCurrentHash, allowUnhealthy }) => {
+        try {
+            const parsed = parseManifest(manifest);
+            const result = await applyManifest(client, parsed, {
+                planToken,
+                mode,
+                expectedCurrentHash,
+                allowUnhealthy,
+            });
+            return text({ ...result, provisioning: redactForTransport(result.provisioning, conn.transport) });
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('scaffold_integration', {
+        title: 'Generate the host application integration code',
+        description: 'Return the source a host application needs: the identity relay for its backend (the one security-critical piece, built on appilot-server), the widget boot call, and a client-action example. Returns file CONTENTS for you to write into the repository; this server never touches the filesystem. Pick the framework that matches the host.',
+        inputSchema: {
+            framework: z.enum(['next', 'express', 'fastify', 'hono', 'remix', 'sveltekit']),
+            widgetKey: z.string().optional(),
+            widgetScriptUrl: z.string().optional(),
+            idNamespace: z.string().optional(),
+        },
+    }, async ({ framework, widgetKey, widgetScriptUrl, idNamespace }) => {
+        try {
+            return text(scaffoldIntegration({
+                framework,
+                widgetScriptUrl: widgetScriptUrl ?? DEFAULT_WIDGET_SCRIPT_URL,
+                apiUrl: conn.baseUrl || null,
+                widgetKey: widgetKey ?? null,
+                idNamespace,
+            }));
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('verify_integration', {
+        title: 'Verify the integration against the running app',
+        description: 'Load the real page and report what is actually true: is the Appilot instance reachable, does the page\'s domain resolve to a tenant, is the widget referenced, does the identity relay answer correctly for an unauthenticated caller, does the widget boot in a browser, and are there Appilot errors in the console. This catches the class of failures no static check can see (a stale bundle, a rotated key, a domain resolving to the wrong tenant). The browser half needs Playwright and is skipped, not failed, without it.',
+        inputSchema: {
+            url: z.string().url(),
+            appId: z.number().int().optional(),
+            tokenEndpoint: z.string().optional(),
+        },
+    }, async ({ url, appId, tokenEndpoint }) => {
+        try {
+            const result = await verifyIntegration(client, {
+                url,
+                appId: appId ?? conn.defaultAppId ?? null,
+                tokenEndpoint,
+                storageStatePath: conn.soakStorageStatePath,
+            });
+            return text(result);
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    server.registerTool('soak_selectors', {
+        title: 'Soak control selectors against the live DOM',
+        description: 'Load a real page in a headless browser and check that each of the app\'s control selectors resolves to at least one element. Catches unstable selectors (e.g. auto-generated ids) that pass every static check but are gone on the next render. Requires Playwright; an authenticated site session can be supplied via APPILOT_SOAK_STORAGE_STATE.',
+        inputSchema: { url: z.string().url(), appId: z.number().int().optional() },
+    }, async ({ url, appId }) => {
+        try {
+            const id = resolveAppId(appId);
+            const controls = await client.listControls(id);
+            const selectors = controls
+                .map(c => ({ semantic_id: String(c.semantic_id ?? ''), locator: String(c.locator ?? c.locator_value ?? '') }))
+                .filter(s => s.locator);
+            const result = await soakSelectors({ url, selectors, storageStatePath: conn.soakStorageStatePath });
+            return text(result);
+        }
+        catch (err) {
+            return errorText(err);
+        }
+    });
+    return server;
+}

package/dist/soak.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Live DOM soak: drive the real rendered page to confirm a plan's control
+ * selectors actually resolve (and optionally that executing the flow produces
+ * the expected effect). This is what catches an unstable selector like
+ * `#nc-vue-30` that passes every static check but is gone on the next render.
+ *
+ * Playwright is a peer dependency, lazily imported so the rest of the server
+ * works without it. If it is absent we return a clear, non-fatal message.
+ * An authenticated site session can be supplied via a Playwright storageState
+ * JSON file (APPILOT_SOAK_STORAGE_STATE).
+ */
+export interface SoakSelector {
+    semantic_id: string;
+    locator: string;
+}
+export interface SoakResult {
+    available: boolean;
+    url?: string;
+    selectors?: Array<{
+        semantic_id: string;
+        locator: string;
+        resolved: boolean;
+        count: number;
+    }>;
+    note?: string;
+}
+export declare function soakSelectors(opts: {
+    url: string;
+    selectors: SoakSelector[];
+    storageStatePath?: string;
+    timeoutMs?: number;
+}): Promise<SoakResult>;

package/dist/soak.js

@@ -0,0 +1,51 @@
+/**
+ * Live DOM soak: drive the real rendered page to confirm a plan's control
+ * selectors actually resolve (and optionally that executing the flow produces
+ * the expected effect). This is what catches an unstable selector like
+ * `#nc-vue-30` that passes every static check but is gone on the next render.
+ *
+ * Playwright is a peer dependency, lazily imported so the rest of the server
+ * works without it. If it is absent we return a clear, non-fatal message.
+ * An authenticated site session can be supplied via a Playwright storageState
+ * JSON file (APPILOT_SOAK_STORAGE_STATE).
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+async function loadPlaywright() {
+    try {
+        // Lazy, optional: absent Playwright must not break the server.
+        return await import('playwright');
+    }
+    catch {
+        return null;
+    }
+}
+export async function soakSelectors(opts) {
+    const playwright = await loadPlaywright();
+    if (!playwright) {
+        return {
+            available: false,
+            note: 'Playwright is not installed. Run `pnpm add -D playwright && npx playwright install chromium` in the MCP package to enable live DOM soak.',
+        };
+    }
+    const browser = await playwright.chromium.launch({ headless: true });
+    try {
+        const context = await browser.newContext(opts.storageStatePath ? { storageState: opts.storageStatePath } : undefined);
+        const page = await context.newPage();
+        await page.goto(opts.url, { waitUntil: 'domcontentloaded', timeout: opts.timeoutMs ?? 20000 });
+        const selectors = [];
+        for (const s of opts.selectors) {
+            let count = 0;
+            try {
+                count = await page.locator(s.locator).count();
+            }
+            catch {
+                count = 0;
+            }
+            selectors.push({ semantic_id: s.semantic_id, locator: s.locator, resolved: count > 0, count });
+        }
+        return { available: true, url: opts.url, selectors };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/verify.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `verify_integration`: load the real thing and report what is actually true.
+ *
+ * Every integration failure recorded in `l3/docs/agent-first.md` was invisible
+ * from the source: a widget bundle nine days older than the feature it was meant
+ * to ship, a `presentation` column still NULL because the rows predated the
+ * seed, a widget secret rotated under a running process, a tenant quietly
+ * resolving to the default organization. Static validation cannot see any of
+ * them. This can, and that is what lets a coding agent correct itself instead of
+ * filing a support ticket.
+ *
+ * The checks degrade rather than fail: each one reports pass, fail, or skipped
+ * with a reason, so a run without Playwright still answers the network half.
+ */
+import type { AppilotClient } from './client.js';
+export type CheckStatus = 'pass' | 'fail' | 'warn' | 'skip';
+export interface IntegrationCheck {
+    id: string;
+    title: string;
+    status: CheckStatus;
+    detail: string;
+    /** What to do about it. Present on anything that is not a pass. */
+    fix?: string;
+}
+export interface VerifyIntegrationResult {
+    url: string;
+    ok: boolean;
+    checks: IntegrationCheck[];
+    summary: string;
+}
+interface VerifyOptions {
+    url: string;
+    appId?: number | null;
+    /** Path the host serves its identity relay on. Default `/api/widget/token`. */
+    tokenEndpoint?: string;
+    storageStatePath?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function verifyIntegration(client: AppilotClient, options: VerifyOptions): Promise<VerifyIntegrationResult>;
+export {};

package/dist/verify.js

@@ -0,0 +1,149 @@
+/**
+ * `verify_integration`: load the real thing and report what is actually true.
+ *
+ * Every integration failure recorded in `l3/docs/agent-first.md` was invisible
+ * from the source: a widget bundle nine days older than the feature it was meant
+ * to ship, a `presentation` column still NULL because the rows predated the
+ * seed, a widget secret rotated under a running process, a tenant quietly
+ * resolving to the default organization. Static validation cannot see any of
+ * them. This can, and that is what lets a coding agent correct itself instead of
+ * filing a support ticket.
+ *
+ * The checks degrade rather than fail: each one reports pass, fail, or skipped
+ * with a reason, so a run without Playwright still answers the network half.
+ */
+const WIDGET_MARKERS = ['appilot.esm.js', 'appilot.js', 'bootAppilotWidget', 'data-api-key', 'appilot-widget'];
+function check(id, title, status, detail, fix) {
+    return { id, title, status, detail, ...(fix ? { fix } : {}) };
+}
+/**
+ * Probe the relay without a session. A correctly mounted relay answers 401 with
+ * its typed code; 404 means it is not mounted at all, which is the single most
+ * common wiring mistake and is otherwise only visible as "the assistant says I
+ * am not signed in".
+ */
+async function checkTokenEndpoint(origin, path, doFetch) {
+    const endpoint = new URL(path, origin).toString();
+    let res;
+    try {
+        res = await doFetch(endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: '{}',
+        });
+    }
+    catch (error) {
+        return check('token-endpoint', 'Identity relay reachable', 'fail', `POST ${endpoint} did not respond (${error.message}).`, 'Mount the relay with createWidgetTokenHandler from appilot-server.');
+    }
+    if (res.status === 404) {
+        return check('token-endpoint', 'Identity relay reachable', 'fail', `POST ${endpoint} returned 404.`, 'The relay is not mounted at this path. Mount createWidgetTokenHandler there, or pass the path you actually use as tokenEndpoint.');
+    }
+    if (res.status === 401 || res.status === 403) {
+        return check('token-endpoint', 'Identity relay reachable', 'pass', `POST ${endpoint} answered ${res.status} for an unauthenticated caller, which is the correct refusal.`);
+    }
+    if (res.ok) {
+        return check('token-endpoint', 'Identity relay reachable', 'warn', `POST ${endpoint} returned a token to a caller with no session.`, 'resolveUser must derive the user from a credential the host trusts and return null otherwise. A relay that mints a token for anyone hands every visitor an identity.');
+    }
+    return check('token-endpoint', 'Identity relay reachable', 'warn', `POST ${endpoint} returned ${res.status}.`, 'Expected 401 for an unauthenticated probe. A 5xx usually means the relay is mounted but misconfigured (missing key or secret).');
+}
+/**
+ * Try Playwright for the half only a browser can answer: does the widget
+ * actually boot on the page. Absence of Playwright is a skip, never a crash,
+ * which is the same posture soak_selectors takes.
+ */
+async function checkWidgetBoots(url, storageStatePath) {
+    let chromium;
+    try {
+        ({ chromium } = await import('playwright'));
+    }
+    catch {
+        return [
+            check('widget-boot', 'Widget boots on the page', 'skip', 'Playwright is not installed.', 'npm i -D playwright && npx playwright install chromium, then re-run to check the browser half.'),
+        ];
+    }
+    const browser = await chromium.launch();
+    try {
+        const context = await browser.newContext(storageStatePath ? { storageState: storageStatePath } : {});
+        const page = await context.newPage();
+        const consoleErrors = [];
+        page.on('console', message => {
+            if (message.type() === 'error')
+                consoleErrors.push(message.text());
+        });
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+        // The widget mounts its own element under documentElement, so a plain
+        // selector on body would miss it (see docs/architecture/in-page-overlays.md).
+        const mounted = await page
+            .waitForFunction(() => Boolean(document.querySelector('appilot-widget') ||
+            document.querySelector('[data-appilot-surface]') ||
+            window.Appilot), undefined, { timeout: 15_000 })
+            .then(() => true)
+            .catch(() => false);
+        const checks = [
+            mounted
+                ? check('widget-boot', 'Widget boots on the page', 'pass', 'The widget mounted and window.Appilot is present.')
+                : check('widget-boot', 'Widget boots on the page', 'fail', 'No Appilot surface appeared within 15s.', 'Check that the loader script is on the page, that its origin is reachable (CSP script-src), and that the domain is registered or a wk_test_ key is set.'),
+        ];
+        const appilotErrors = consoleErrors.filter(e => /appilot/i.test(e));
+        if (appilotErrors.length > 0) {
+            checks.push(check('console-errors', 'No Appilot errors in the console', 'fail', appilotErrors.slice(0, 5).join(' | '), 'Read the first error: a 401 points at the key or the relay, a CSP violation at script-src or connect-src.'));
+        }
+        else {
+            checks.push(check('console-errors', 'No Appilot errors in the console', 'pass', 'Clean.'));
+        }
+        return checks;
+    }
+    finally {
+        await browser.close();
+    }
+}
+export async function verifyIntegration(client, options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const checks = [];
+    const target = new URL(options.url);
+    // 1. The instance answers at all.
+    try {
+        const caps = await client.getCapabilities();
+        checks.push(check('instance', 'Appilot instance reachable', 'pass', `Version ${caps.appVersion ?? 'unknown'}.`));
+    }
+    catch (error) {
+        checks.push(check('instance', 'Appilot instance reachable', 'fail', error.message, 'Check APPILOT_BASE_URL. Everything below depends on this.'));
+    }
+    // 2. Does the page's own hostname resolve to a tenant? This is the check
+    // that catches a widget pointed at an unregistered domain, which silently
+    // degrades to the key's org (dev fallback) or to no org at all.
+    try {
+        const resolution = (await client.checkDomain(target.hostname));
+        const registered = resolution.status === 'registered' || resolution.registered === true;
+        checks.push(registered
+            ? check('domain', 'Domain resolves to a tenant', 'pass', `${target.hostname} is registered.`)
+            : check('domain', 'Domain resolves to a tenant', target.hostname === 'localhost' ? 'warn' : 'fail', `${target.hostname} is not registered (status: ${String(resolution.status ?? 'unknown')}).`, 'Register the domain, or use a wk_test_ key for local development. On an unregistered production domain the tenant cannot be resolved from the page.'));
+    }
+    catch (error) {
+        checks.push(check('domain', 'Domain resolves to a tenant', 'warn', error.message));
+    }
+    // 3. Is the widget referenced by the served HTML at all?
+    try {
+        const res = await doFetch(options.url, { headers: { Accept: 'text/html' } });
+        const html = await res.text();
+        const found = WIDGET_MARKERS.filter(marker => html.includes(marker));
+        checks.push(found.length > 0
+            ? check('markup', 'Widget referenced by the page', 'pass', `Found: ${found.join(', ')}.`)
+            : check('markup', 'Widget referenced by the page', 'warn', 'No Appilot loader found in the served HTML.', 'This is expected when the widget boots from client-side JavaScript. The browser check below is the authority.'));
+    }
+    catch (error) {
+        checks.push(check('markup', 'Widget referenced by the page', 'fail', `Could not fetch ${options.url}: ${error.message}`));
+    }
+    // 4. The identity relay.
+    checks.push(await checkTokenEndpoint(target.origin, options.tokenEndpoint ?? '/api/widget/token', doFetch));
+    // 5. The browser half.
+    checks.push(...(await checkWidgetBoots(options.url, options.storageStatePath)));
+    const failed = checks.filter(c => c.status === 'fail');
+    const warned = checks.filter(c => c.status === 'warn');
+    const summary = failed.length
+        ? `${failed.length} check(s) failed: ${failed.map(c => c.id).join(', ')}.`
+        : warned.length
+            ? `All checks passed with ${warned.length} warning(s).`
+            : 'Integration verified end to end.';
+    return { url: options.url, ok: failed.length === 0, checks, summary };
+}