appilot-mcp 0.1.0 → 0.2.1

package/dist/inspect.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Read a page and report what an author needs to register it.
+ *
+ * This is the half of the tool surface that was missing for the developer who
+ * says "look at this screen and configure it". Everything else could read the
+ * configuration and validate it; nothing could see the thing being configured,
+ * so a control's locator had to come from a human picking it in the extension.
+ *
+ * Two paths, because the transports differ in what they can run.
+ *
+ *   url   Loads the real page in Playwright. Playwright is an optional peer, so
+ *         this path degrades rather than crashing, exactly as `soak.ts` and
+ *         `verify.ts` do.
+ *   html  Scans pasted markup with no browser. Flat and structural only: it
+ *         reads the attributes on interactive tags in document order and groups
+ *         fields by the form they appear inside. It cannot compute an accessible
+ *         name, and it does not know what is visible. It is what keeps the
+ *         hosted endpoint useful, and it says which of the two produced a
+ *         result so nobody mistakes one for the other.
+ *
+ * A locator candidate is ranked by whether it survives the next render, which
+ * is the only property that matters: an auto-generated id passes every static
+ * check and is gone on redeploy. The `type` on each candidate is an Appilot
+ * `locator_type`, not a CSS selector kind, so the output can be pasted into a
+ * control body unchanged.
+ */
+export type LocatorType = 'id' | 'class_text' | 'aria' | 'xpath' | 'semantic';
+export interface LocatorCandidate {
+    locator: string;
+    type: LocatorType;
+    /** Higher is more likely to still resolve after the next deploy. */
+    stability: 'stable' | 'reasonable' | 'fragile';
+    why: string;
+}
+export interface InspectedElement {
+    tag: string;
+    role: string | null;
+    text: string | null;
+    kind: 'action' | 'field' | 'region';
+    /** Best first. */
+    candidates: LocatorCandidate[];
+    /** Semantic id of an already-configured control whose locator matches. */
+    configuredAs?: string;
+}
+export interface InspectedForm {
+    /** The form's own candidates, for the entry control. */
+    candidates: LocatorCandidate[];
+    fields: InspectedElement[];
+    submit: InspectedElement | null;
+}
+export interface InspectResult {
+    source: 'browser' | 'html';
+    available: boolean;
+    url?: string;
+    /** The path a View would carry, when a URL was given. */
+    viewPath?: string;
+    elements: InspectedElement[];
+    forms: InspectedForm[];
+    /** What is already registered for this view, so nothing is authored twice. */
+    alreadyConfigured?: {
+        controls: string[];
+        forms: string[];
+        zones: string[];
+    };
+    note?: string;
+}
+/**
+ * Rank the ways to address one element.
+ *
+ * Order is the contract: whoever consumes this takes the first candidate unless
+ * they have a reason not to, so the first candidate must be the one that ages
+ * best, never the shortest.
+ */
+export declare function rankCandidates(attrs: Record<string, string>, tag: string, text: string | null): LocatorCandidate[];
+/**
+ * Scan pasted markup for interactive elements.
+ *
+ * Deliberately flat. It walks tag openings in document order and tracks only one
+ * nesting fact, whether it is currently inside a form, because that is the one
+ * relationship the content model needs and the one a regex can get right.
+ */
+export declare function inspectHtml(html: string): InspectResult;
+export declare function inspectPage(opts: {
+    url?: string;
+    html?: string;
+    storageStatePath?: string;
+    timeoutMs?: number;
+}): Promise<InspectResult>;

package/dist/inspect.js

@@ -0,0 +1,384 @@
+/**
+ * Read a page and report what an author needs to register it.
+ *
+ * This is the half of the tool surface that was missing for the developer who
+ * says "look at this screen and configure it". Everything else could read the
+ * configuration and validate it; nothing could see the thing being configured,
+ * so a control's locator had to come from a human picking it in the extension.
+ *
+ * Two paths, because the transports differ in what they can run.
+ *
+ *   url   Loads the real page in Playwright. Playwright is an optional peer, so
+ *         this path degrades rather than crashing, exactly as `soak.ts` and
+ *         `verify.ts` do.
+ *   html  Scans pasted markup with no browser. Flat and structural only: it
+ *         reads the attributes on interactive tags in document order and groups
+ *         fields by the form they appear inside. It cannot compute an accessible
+ *         name, and it does not know what is visible. It is what keeps the
+ *         hosted endpoint useful, and it says which of the two produced a
+ *         result so nobody mistakes one for the other.
+ *
+ * A locator candidate is ranked by whether it survives the next render, which
+ * is the only property that matters: an auto-generated id passes every static
+ * check and is gone on redeploy. The `type` on each candidate is an Appilot
+ * `locator_type`, not a CSS selector kind, so the output can be pasted into a
+ * control body unchanged.
+ */
+/**
+ * Ids a framework generated. Registering one of these is the single most common
+ * way a configuration passes every check and then does nothing on the real page.
+ */
+const GENERATED_ID = [
+    /^(nc|mui|radix|headlessui|chakra|mantine|ember|ext-gen|yui)[-_:]/i,
+    /^:r[0-9a-z]+:$/i,
+    /^[a-f0-9]{8,}$/i,
+    /\d{4,}$/,
+    /^react-aria\d+$/i,
+];
+function idLooksGenerated(id) {
+    return GENERATED_ID.some(re => re.test(id));
+}
+const TEST_ATTRS = ['data-testid', 'data-test-id', 'data-test', 'data-qa', 'data-cy', 'data-automation-id'];
+const ACTION_TAGS = new Set(['button', 'a', 'summary']);
+const FIELD_TAGS = new Set(['input', 'select', 'textarea']);
+const REGION_TAGS = new Set(['nav', 'main', 'aside', 'header', 'footer', 'section', 'form']);
+/**
+ * Rank the ways to address one element.
+ *
+ * Order is the contract: whoever consumes this takes the first candidate unless
+ * they have a reason not to, so the first candidate must be the one that ages
+ * best, never the shortest.
+ */
+export function rankCandidates(attrs, tag, text) {
+    const out = [];
+    const q = (v) => v.replace(/"/g, '\\"');
+    for (const attr of TEST_ATTRS) {
+        const value = attrs[attr];
+        if (value) {
+            out.push({
+                locator: `[${attr}="${q(value)}"]`,
+                type: 'class_text',
+                stability: 'stable',
+                why: 'A test attribute exists to be addressed and is not rewritten by a redesign.',
+            });
+        }
+    }
+    if (attrs['aria-label']) {
+        out.push({
+            locator: attrs['aria-label'],
+            type: 'aria',
+            stability: 'stable',
+            why: 'An accessible name is user-visible and changes only when the interface changes.',
+        });
+    }
+    const id = attrs.id;
+    if (id) {
+        if (idLooksGenerated(id)) {
+            out.push({
+                locator: `#${id}`,
+                type: 'id',
+                stability: 'fragile',
+                why: 'This id looks generated by a framework. It will differ on the next render. Do not register it.',
+            });
+        }
+        else {
+            out.push({
+                locator: `#${id}`,
+                type: 'id',
+                stability: 'stable',
+                why: 'An authored id is addressed directly and survives styling changes.',
+            });
+        }
+    }
+    if (attrs.name && (FIELD_TAGS.has(tag) || tag === 'form')) {
+        out.push({
+            locator: `[name="${q(attrs.name)}"]`,
+            type: 'class_text',
+            stability: 'stable',
+            why: 'A field name is part of the form contract, so it outlives the markup around it.',
+        });
+    }
+    if (attrs.placeholder) {
+        out.push({
+            locator: `[placeholder="${q(attrs.placeholder)}"]`,
+            type: 'class_text',
+            stability: 'reasonable',
+            why: 'A placeholder is user-visible copy, so it moves with translation and rewording.',
+        });
+    }
+    if (attrs.role && text) {
+        out.push({
+            locator: `${attrs.role}:${text}`,
+            type: 'aria',
+            stability: 'reasonable',
+            why: 'Role plus accessible name, which is how a person finds the element.',
+        });
+    }
+    if (text && text.length <= 60) {
+        out.push({
+            locator: text,
+            type: 'semantic',
+            stability: 'reasonable',
+            why: 'Visible text. Correct until the copy is reworded or translated.',
+        });
+    }
+    if (out.length === 0) {
+        out.push({
+            locator: tag,
+            type: 'class_text',
+            stability: 'fragile',
+            why: 'Nothing addressable on this element. Ask the app team for a data attribute before registering it.',
+        });
+    }
+    const rank = { stable: 0, reasonable: 1, fragile: 2 };
+    return out.sort((a, b) => rank[a.stability] - rank[b.stability]);
+}
+function classify(tag, role) {
+    if (FIELD_TAGS.has(tag))
+        return 'field';
+    if (ACTION_TAGS.has(tag) || role === 'button' || role === 'link' || role === 'menuitem')
+        return 'action';
+    return 'region';
+}
+/* -------------------------------------------------------------------------- */
+/* Pasted markup                                                              */
+/* -------------------------------------------------------------------------- */
+const TAG_RE = /<\/?([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'>`]+))?)*)\s*\/?>/g;
+const ATTR_RE = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>`]+)))?/g;
+function parseAttrs(raw) {
+    const attrs = {};
+    ATTR_RE.lastIndex = 0;
+    let m;
+    while ((m = ATTR_RE.exec(raw)) !== null) {
+        const name = m[1].toLowerCase();
+        attrs[name] = m[2] ?? m[3] ?? m[4] ?? '';
+    }
+    return attrs;
+}
+function stripTags(html) {
+    return html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Scan pasted markup for interactive elements.
+ *
+ * Deliberately flat. It walks tag openings in document order and tracks only one
+ * nesting fact, whether it is currently inside a form, because that is the one
+ * relationship the content model needs and the one a regex can get right.
+ */
+export function inspectHtml(html) {
+    const elements = [];
+    const forms = [];
+    let current = null;
+    TAG_RE.lastIndex = 0;
+    let match;
+    while ((match = TAG_RE.exec(html)) !== null) {
+        const raw = match[0];
+        const tag = match[1].toLowerCase();
+        const closing = raw.startsWith('</');
+        if (tag === 'form') {
+            if (closing) {
+                if (current)
+                    forms.push(current);
+                current = null;
+            }
+            else {
+                const attrs = parseAttrs(match[2] ?? '');
+                current = { candidates: rankCandidates(attrs, 'form', null), fields: [], submit: null };
+            }
+            continue;
+        }
+        if (closing)
+            continue;
+        if (!ACTION_TAGS.has(tag) && !FIELD_TAGS.has(tag) && !REGION_TAGS.has(tag))
+            continue;
+        const attrs = parseAttrs(match[2] ?? '');
+        if (attrs.type === 'hidden')
+            continue;
+        // Text runs to the matching close tag when there is one on the same
+        // nesting level. Good enough for a button label, which is what it is for.
+        let text = null;
+        if (!FIELD_TAGS.has(tag)) {
+            const close = html.indexOf(`</${tag}`, match.index + raw.length);
+            if (close > -1 && close - match.index < 2000) {
+                const inner = stripTags(html.slice(match.index + raw.length, close));
+                text = inner ? inner.slice(0, 120) : null;
+            }
+        }
+        if (!text && attrs.value && FIELD_TAGS.has(tag))
+            text = attrs.value.slice(0, 120);
+        const role = attrs.role ?? null;
+        const element = {
+            tag,
+            role,
+            text,
+            kind: classify(tag, role),
+            candidates: rankCandidates(attrs, tag, text),
+        };
+        const isSubmit = tag === 'button'
+            ? attrs.type !== 'button' && attrs.type !== 'reset'
+            : tag === 'input' && attrs.type === 'submit';
+        if (current) {
+            if (isSubmit && !current.submit)
+                current.submit = element;
+            else if (element.kind === 'field')
+                current.fields.push(element);
+            else
+                elements.push(element);
+        }
+        else {
+            elements.push(element);
+        }
+    }
+    if (current)
+        forms.push(current);
+    return {
+        source: 'html',
+        available: true,
+        elements,
+        forms,
+        note: 'Scanned pasted markup with no browser. Visibility, computed roles and accessible names are unknown here, and nothing confirms these selectors resolve on the running page. Run soak_selectors, or inspect by URL from a local server, before trusting a locator.',
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Live page                                                                  */
+/* -------------------------------------------------------------------------- */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+async function loadPlaywright() {
+    try {
+        return await import('playwright');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What runs inside the page. Returns raw attribute bags, so the ranking stays
+ * here in one place and is unit-testable without a browser.
+ */
+const EXTRACT = `() => {
+  const out = [];
+  const sel = 'button, a[href], input, select, textarea, summary, [role="button"], [role="link"], [role="menuitem"], nav, main, aside, header, footer, form';
+  for (const el of document.querySelectorAll(sel)) {
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') continue;
+    if (rect.width === 0 && rect.height === 0 && el.tagName !== 'FORM') continue;
+    const attrs = {};
+    for (const a of el.attributes) attrs[a.name.toLowerCase()] = a.value;
+    const label = (el.getAttribute('aria-label') || el.textContent || '').replace(/\\s+/g, ' ').trim();
+    out.push({
+      tag: el.tagName.toLowerCase(),
+      attrs,
+      text: label ? label.slice(0, 120) : null,
+      formIndex: el.form ? Array.prototype.indexOf.call(document.forms, el.form) : -1,
+      isSubmit: (el.tagName === 'BUTTON' && el.type !== 'button' && el.type !== 'reset') || (el.tagName === 'INPUT' && el.type === 'submit'),
+    });
+  }
+  return out;
+}`;
+export async function inspectPage(opts) {
+    if (opts.html)
+        return inspectHtml(opts.html);
+    if (!opts.url) {
+        return {
+            source: 'html',
+            available: false,
+            elements: [],
+            forms: [],
+            note: 'Pass either a url to load, or html to scan.',
+        };
+    }
+    const playwright = await loadPlaywright();
+    if (!playwright) {
+        return {
+            source: 'browser',
+            available: false,
+            elements: [],
+            forms: [],
+            note: 'No browser is available here, so this page cannot be loaded. Two ways forward, in order of preference: ask the person to open the page, copy the outerHTML of the region they care about, and call this tool again with `html` instead of `url`; or run the Appilot MCP server locally over stdio, where Playwright can be installed (pnpm add -D playwright && npx playwright install chromium).',
+        };
+    }
+    let browser;
+    try {
+        browser = await playwright.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        return {
+            source: 'browser',
+            available: false,
+            elements: [],
+            forms: [],
+            note: `A browser could not be launched: ${err instanceof Error ? err.message : String(err)}. Run npx playwright install chromium, or pass html instead of url.`,
+        };
+    }
+    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 raw = (await page.evaluate(EXTRACT));
+        const elements = [];
+        const formMap = new Map();
+        for (const item of raw) {
+            const role = item.attrs.role ?? null;
+            const element = {
+                tag: item.tag,
+                role,
+                text: item.text,
+                kind: classify(item.tag, role),
+                candidates: rankCandidates(item.attrs, item.tag, item.text),
+            };
+            if (item.tag === 'form') {
+                const index = Array.from(formMap.keys()).length;
+                formMap.set(index, { candidates: element.candidates, fields: [], submit: null });
+                continue;
+            }
+            const form = item.formIndex >= 0 ? formMap.get(item.formIndex) : undefined;
+            if (form) {
+                if (item.isSubmit && !form.submit)
+                    form.submit = element;
+                else if (element.kind === 'field')
+                    form.fields.push(element);
+                else
+                    elements.push(element);
+            }
+            else {
+                elements.push(element);
+            }
+        }
+        let viewPath;
+        try {
+            viewPath = new URL(opts.url).pathname;
+        }
+        catch {
+            viewPath = undefined;
+        }
+        return {
+            source: 'browser',
+            available: true,
+            url: opts.url,
+            viewPath,
+            elements,
+            forms: Array.from(formMap.values()),
+        };
+    }
+    catch (err) {
+        // A navigation failure is a finding, not a crash. The same rule the soak
+        // and the integration verifier follow: report it and let the caller act.
+        return {
+            source: 'browser',
+            available: false,
+            url: opts.url,
+            elements: [],
+            forms: [],
+            note: `The page could not be inspected: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch {
+            /* closing a browser that already died is not a failure worth reporting */
+        }
+    }
+}

package/dist/redaction.d.ts

@@ -8,9 +8,14 @@
  * claude.ai), where it is stored, summarized, and outside the operator's
  * control.
  *
- * Only one value in the whole surface is affected: the widget SECRET minted
- * during provisioning. The widget KEY beside it is a publishable identifier
- * that is meant to sit in public HTML, so it travels either way.
+ * Two values are affected, and they travel in opposite directions. The widget
+ * SECRET minted during provisioning comes back in a result, so it is stripped
+ * from one. A tool's vault credential goes the other way, in a tool ARGUMENT,
+ * so it is refused before the call is made: over the remote transport the
+ * argument is already stored in the third party's conversation by the time this
+ * server sees it, and there is no useful way to unsend it. The widget KEY beside
+ * the secret is a publishable identifier meant to sit in public HTML, so it
+ * travels either way.
  */
 export declare const SECRET_WITHHELD_NOTICE = "The widget secret is not returned over the remote transport, because a tool result here is stored in this conversation. Read it once from the Backoffice widget-keys page, or run the Appilot MCP server locally over stdio.";
 interface ProvisionLike {
@@ -27,4 +32,14 @@ interface ProvisionLike {
  * minted (a converging run never mints one).
  */
 export declare function redactForTransport<T extends ProvisionLike>(result: T, transport: 'stdio' | 'http' | undefined): T;
+export declare const CREDENTIAL_REFUSED_NOTICE = "A tool credential (auth_secret) cannot be set over the remote transport, because a tool argument here is stored in this conversation before it reaches Appilot. Two ways through: run the Appilot MCP server locally over stdio and set it there, or open the tool in the Backoffice and paste the credential. Everything else about this entity can be written from here; send the same call again without auth_secret.";
+/**
+ * Refuse a write that would carry a vault credential across the remote
+ * transport. Returns null when the call may proceed.
+ *
+ * The check is on the field name rather than on the entity kind on purpose. A
+ * credential is refused wherever it appears, so a body that reaches the tool
+ * routes by some other path cannot slip one through.
+ */
+export declare function refuseSecretOverRemote(body: unknown, transport: 'stdio' | 'http' | undefined): string | null;
 export {};

package/dist/redaction.js

@@ -8,9 +8,14 @@
  * claude.ai), where it is stored, summarized, and outside the operator's
  * control.
  *
- * Only one value in the whole surface is affected: the widget SECRET minted
- * during provisioning. The widget KEY beside it is a publishable identifier
- * that is meant to sit in public HTML, so it travels either way.
+ * Two values are affected, and they travel in opposite directions. The widget
+ * SECRET minted during provisioning comes back in a result, so it is stripped
+ * from one. A tool's vault credential goes the other way, in a tool ARGUMENT,
+ * so it is refused before the call is made: over the remote transport the
+ * argument is already stored in the third party's conversation by the time this
+ * server sees it, and there is no useful way to unsend it. The widget KEY beside
+ * the secret is a publishable identifier meant to sit in public HTML, so it
+ * travels either way.
  */
 export const SECRET_WITHHELD_NOTICE = 'The widget secret is not returned over the remote transport, because a tool result here is stored in this conversation. Read it once from the Backoffice widget-keys page, or run the Appilot MCP server locally over stdio.';
 /**
@@ -31,3 +36,22 @@ export function redactForTransport(result, transport) {
     widgetKey.secretWithheld = SECRET_WITHHELD_NOTICE;
     return { ...result, widgetKey };
 }
+export const CREDENTIAL_REFUSED_NOTICE = 'A tool credential (auth_secret) cannot be set over the remote transport, because a tool argument here is stored in this conversation before it reaches Appilot. Two ways through: run the Appilot MCP server locally over stdio and set it there, or open the tool in the Backoffice and paste the credential. Everything else about this entity can be written from here; send the same call again without auth_secret.';
+/**
+ * Refuse a write that would carry a vault credential across the remote
+ * transport. Returns null when the call may proceed.
+ *
+ * The check is on the field name rather than on the entity kind on purpose. A
+ * credential is refused wherever it appears, so a body that reaches the tool
+ * routes by some other path cannot slip one through.
+ */
+export function refuseSecretOverRemote(body, transport) {
+    if (transport !== 'http')
+        return null;
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const value = body.auth_secret;
+    if (value === undefined || value === null || value === '')
+        return null;
+    return CREDENTIAL_REFUSED_NOTICE;
+}

package/dist/remote/consent.d.ts

@@ -1,29 +1,31 @@
-/**
- * The consent screen of the remote MCP service.
- *
- * This is the one page a person sees when connecting ChatGPT or Claude to their
- * Appilot instance. It asks for a service token rather than an Appilot password
- * on purpose: the connector needs a long-lived, scoped, revocable credential,
- * which is exactly what a service token is and exactly what a password is not.
- * A password would also make this host a credential-collection surface for the
- * whole account, and it can grant no less than everything.
- *
- * Plain server-rendered HTML with no external assets, so it renders inside the
- * in-app browsers ChatGPT and Claude use for the OAuth hop.
- */
+import { type ConsentLocale } from './consentMessages.js';
+export declare function escapeHtml(value: string): string;
 export interface ConsentPageOptions {
-    /** Sealed authorization request, round-tripped through the form. */
     request: string;
-    /** Where the form posts. */
     action: string;
-    /** Display name of the MCP client asking for access. */
     clientName: string;
-    /** The Appilot backend this deployment serves, shown so the person can check it. */
     baseUrl: string;
-    /** Scopes the client asked for. */
     scopes: string[];
-    /** Set after a failed attempt so the person can correct it in place. */
+    backofficeUrl?: string;
     error?: string;
+    locale?: ConsentLocale;
 }
 export declare function renderConsentPage(opts: ConsentPageOptions): string;
-export declare function renderErrorPage(title: string, detail: string): string;
+export interface ConfirmPageOptions {
+    request: string;
+    action: string;
+    baseUrl: string;
+    scopes: string[];
+    withheldScopes: string[];
+    unavailableScopes?: string[];
+    organizationId: number | null;
+    organizationName?: string | null;
+    appId: number | null;
+    appName?: string | null;
+    appScoped: boolean;
+    clientName?: string;
+    backofficeUrl?: string;
+    locale?: ConsentLocale;
+}
+export declare function renderConfirmPage(opts: ConfirmPageOptions): string;
+export declare function renderErrorPage(title: string, detail: string, locale?: ConsentLocale): string;