appilot-mcp 0.1.1 → 0.3.0

package/dist/soak.js

@@ -27,7 +27,16 @@ export async function soakSelectors(opts) {
             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 });
+    let browser;
+    try {
+        browser = await playwright.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        return {
+            available: false,
+            note: `A browser could not be launched: ${err instanceof Error ? err.message : String(err)}. Run npx playwright install chromium.`,
+        };
+    }
     try {
         const context = await browser.newContext(opts.storageStatePath ? { storageState: opts.storageStatePath } : undefined);
         const page = await context.newPage();
@@ -45,6 +54,17 @@ export async function soakSelectors(opts) {
         }
         return { available: true, url: opts.url, selectors };
     }
+    catch (err) {
+        // A soak that cannot reach the page is a reportable outcome, not a crash:
+        // the caller asked whether the selectors resolve and the answer is "the
+        // page did not load", which is actionable on its own.
+        return {
+            available: true,
+            url: opts.url,
+            note: `The page could not be loaded: ${err instanceof Error ? err.message : String(err)}`,
+            selectors: [],
+        };
+    }
     finally {
         await browser.close();
     }

package/dist/templates.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Valid skeletons for each configurable entity.
+ *
+ * Pure: no SDK, no network. The instance's own vocabularies are passed in from
+ * `capabilities` rather than restated here, so a template can never advertise an
+ * enum value the write path rejects.
+ *
+ * Why this exists. Two authoring failures repeat, and both are answerable
+ * before the write rather than after it. A container field the entity kind
+ * declares is left out, and the import answers with a path the author then has
+ * to decode. And an enum value is guessed, because a brand-new app exports empty
+ * arrays and there was no example to copy: an agent reading a live page writes
+ * `locator_type: "css"`, which is not one of the kinds.
+ */
+import type { ConfigEntityKind } from './client.js';
+/**
+ * The closed enums an instance publishes on `capabilities.entityVocabularies`.
+ *
+ * The group keys are the instance's own, and they are the PLURAL table-ish names
+ * (`controls`, `knowledge_content`, `action_plans`), not the singular entity
+ * kinds this module is keyed by. Getting that wrong is silent: every lookup
+ * misses, the template offers no vocabulary, and the agent guesses exactly the
+ * value the write path rejects, which is the failure this module exists to
+ * prevent. The `pick` calls below are the one place the two namings meet, and
+ * `test/authoring.test.ts` pins them against what a live instance answers.
+ */
+export interface EntityVocabularies {
+    controls?: {
+        locator_type?: string[];
+        scope?: string[];
+    };
+    knowledge_content?: {
+        scope?: string[];
+        visibility?: string[];
+    };
+    action_plans?: {
+        marker_kinds?: string[];
+    };
+    zones?: {
+        landmark_role?: string[];
+    };
+    [key: string]: unknown;
+}
+export interface EntityTemplate {
+    kind: ConfigEntityKind;
+    /** The request body, with every container field present. */
+    body: Record<string, unknown>;
+    /** Fields the write path refuses without. */
+    required: string[];
+    /** Closed enums that apply to this kind, as THIS instance declares them. */
+    vocabularies: Record<string, string[]>;
+    /** What to get right, in the order it bites. */
+    notes: string[];
+}
+/**
+ * Build the skeleton for one kind.
+ *
+ * `appId` is filled in where the entity is app-scoped, because leaving it null
+ * produces a body that looks complete and is refused.
+ */
+export declare function entityTemplate(kind: ConfigEntityKind, appId: number | null, vocab?: EntityVocabularies): EntityTemplate;
+export declare const TEMPLATE_KINDS: ConfigEntityKind[];

package/dist/templates.js

@@ -0,0 +1,255 @@
+/**
+ * Valid skeletons for each configurable entity.
+ *
+ * Pure: no SDK, no network. The instance's own vocabularies are passed in from
+ * `capabilities` rather than restated here, so a template can never advertise an
+ * enum value the write path rejects.
+ *
+ * Why this exists. Two authoring failures repeat, and both are answerable
+ * before the write rather than after it. A container field the entity kind
+ * declares is left out, and the import answers with a path the author then has
+ * to decode. And an enum value is guessed, because a brand-new app exports empty
+ * arrays and there was no example to copy: an agent reading a live page writes
+ * `locator_type: "css"`, which is not one of the kinds.
+ */
+function pick(vocab, path) {
+    const group = vocab[path[0]];
+    const values = group?.[path[1]];
+    return Array.isArray(values) && values.every(v => typeof v === 'string') ? values : null;
+}
+/**
+ * Build the skeleton for one kind.
+ *
+ * `appId` is filled in where the entity is app-scoped, because leaving it null
+ * produces a body that looks complete and is refused.
+ */
+export function entityTemplate(kind, appId, vocab = {}) {
+    const locatorTypes = pick(vocab, ['controls', 'locator_type']);
+    const controlScopes = pick(vocab, ['controls', 'scope']);
+    const knowledgeScopes = pick(vocab, ['knowledge_content', 'scope']);
+    const knowledgeVisibility = pick(vocab, ['knowledge_content', 'visibility']);
+    const markerKinds = pick(vocab, ['action_plans', 'marker_kinds']);
+    const landmarkRoles = pick(vocab, ['zones', 'landmark_role']);
+    switch (kind) {
+        case 'view':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    domain_id: null,
+                    name: '',
+                    path: '/',
+                    slug: '',
+                    description: '',
+                    entry_path: null,
+                    name_i18n: {},
+                    description_i18n: {},
+                    rules: [],
+                },
+                required: ['app_id', 'domain_id', 'name', 'path'],
+                vocabularies: {},
+                notes: [
+                    'domain_id names one registered hostname. Read the app\'s domains first; a view on an unregistered hostname can never resolve a tenant.',
+                    'path is the route as the browser shows it, and it is half the view\'s identity in a bundle.',
+                    'entry_path, when set, must be path-absolute.',
+                ],
+            };
+        case 'control':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    locator: '',
+                    locator_type: locatorTypes?.[0] ?? '',
+                    label: '',
+                    description: '',
+                    llm_hint: null,
+                    label_i18n: {},
+                    description_i18n: {},
+                    view_path: null,
+                    scope: controlScopes?.[0] ?? '',
+                    prerequisites: [],
+                    form_id: null,
+                    form_order: null,
+                },
+                required: ['app_id', 'semantic_id', 'locator', 'locator_type'],
+                vocabularies: {
+                    ...(locatorTypes ? { locator_type: locatorTypes } : {}),
+                    ...(controlScopes ? { scope: controlScopes } : {}),
+                },
+                notes: [
+                    'locator_type is a closed set and `css` is not in it. A CSS selector list belongs under class_text.',
+                    'A stable locator is a data attribute, an aria role or a placeholder. An auto-generated id or an :nth-child position passes every static check and is gone on the next render.',
+                    'scope=global takes no view_path.',
+                    'A control becomes a FIELD of a form by carrying form_id and form_order, together, on its own row. The form\'s required_field_ids does not create that membership. Create the form first, then patch each field control with the form\'s row id and its fill order counting from 0, or a plan that fills the form is refused with "field does not belong to form".',
+                    'The control that OPENS a form is the form\'s entry_control and must not also be one of its fields.',
+                    'semantic_id is a short English slug that survives a label change, not a slugified UI label.',
+                ],
+            };
+        case 'form':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    label: '',
+                    domain_id: null,
+                    description: '',
+                    llm_hint: null,
+                    label_i18n: {},
+                    description_i18n: {},
+                    view_paths: [],
+                    required_field_ids: [],
+                    submit_control_id: null,
+                    entry_control_id: null,
+                    visibility_rules: null,
+                    field_defaults: null,
+                    prerequisites: [],
+                    is_active: true,
+                },
+                required: ['app_id', 'semantic_id', 'label'],
+                vocabularies: {},
+                notes: [
+                    'The controls a form names must exist first: create them, then the form.',
+                    'entry_control is what OPENS the form, so it cannot also be one of required_field_ids. The three roles are distinct controls: one opens, several are filled, one submits.',
+                    'view_paths cannot be empty: a form nobody can reach from a view is refused.',
+                    'required_field_ids records which of the form\'s EXISTING fields are mandatory, and it does not create membership. So the order is: create the form with an empty required_field_ids, patch each field control with form_id and form_order, then patch the form with required_field_ids.',
+                    'A form without an entry control and a submit control cannot carry a create flow, and the health contract will say so.',
+                ],
+            };
+        case 'tool':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    tool_name: '',
+                    title: '',
+                    description: '',
+                    view_id: null,
+                    parameters: {},
+                    runtime_spec: {},
+                    title_i18n: {},
+                    description_i18n: {},
+                },
+                required: ['app_id', 'tool_name', 'title', 'description'],
+                vocabularies: {},
+                notes: [
+                    'description is what the agent reads to decide whether to call this at all. Write the trigger, not the implementation.',
+                    'runtime_spec is a discriminated union on `kind`. For `http_proxy` it needs `method` and `path_template`, a path on the host application origin; an absolute URL is rejected, because a server-side call is proxied to the app\'s own origin and nowhere else. For `client_action` the page owns the behaviour and registers it at runtime.',
+                    'A server-side tool stores its credential through auth_secret and auth_header_name on this same body. That value is write-only and never comes back on a read.',
+                    'auth_header_name defaults to Authorization and cannot be a hop-by-hop header.',
+                ],
+            };
+        case 'zone':
+            return {
+                kind,
+                body: {
+                    domain_id: null,
+                    app_id: appId,
+                    semantic_id: '',
+                    label: '',
+                    label_i18n: {},
+                    description: '',
+                    description_i18n: {},
+                    selector: '',
+                    landmark_role: null,
+                    parent_zone_id: null,
+                    view_paths: [],
+                },
+                required: ['domain_id', 'semantic_id', 'label', 'selector'],
+                vocabularies: landmarkRoles ? { landmark_role: landmarkRoles } : {},
+                notes: [
+                    'A zone is a passive region the agent refers to. If it can be clicked, it is a control.',
+                    'Zones are domain-scoped, so domain_id is required and app_id only narrows it.',
+                ],
+            };
+        case 'action_plan':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    name: '',
+                    description: '',
+                    sections: [],
+                    form_values: {},
+                    step_narratives_i18n: {},
+                    is_active: true,
+                },
+                required: ['app_id', 'semantic_id'],
+                vocabularies: markerKinds ? { marker_kinds: markerKinds } : {},
+                notes: [
+                    'description is the agent-facing trigger, written as "Use when the user wants to ...", and localized. A weak description means the plan is never adopted.',
+                    'Each step carries exactly one executable marker. Values never go inside a marker; they ride form_values keyed by form.',
+                    'A create flow must enter a value and submit. A plan that only opens or focuses an element does nothing, and that is the most common defect there is.',
+                    'Validate the sections with validate_action_plan before writing them.',
+                ],
+            };
+        case 'knowledge':
+            return {
+                kind,
+                body: {
+                    application_id: appId,
+                    title: '',
+                    description: '',
+                    general_info: '',
+                    notes: '',
+                    url_pattern: null,
+                    domain: null,
+                    language: 'en',
+                    visibility: knowledgeVisibility?.[0] ?? '',
+                    is_active: true,
+                },
+                required: ['title'],
+                vocabularies: {
+                    ...(knowledgeScopes ? { scope: knowledgeScopes } : {}),
+                    ...(knowledgeVisibility ? { visibility: knowledgeVisibility } : {}),
+                },
+                notes: [
+                    'scope is derived from url_pattern, so narrow the article by giving it a pattern rather than by naming a scope.',
+                    'Knowledge carries meaning: workflows, rules, terminology. A step-by-step article is a procedure in the wrong place, and it competes with the action plan that owns it.',
+                    'is_active defaults to false on this endpoint. Set it explicitly when the article should be live.',
+                ],
+            };
+        case 'session_template':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    name: '',
+                    description: '',
+                    mission_prompt: '',
+                    outcome_schema: { type: 'object', properties: {}, required: [] },
+                    variables: [],
+                    allowed_tools: [],
+                    preflight: [],
+                    presentation: null,
+                    kb_doc_ids: null,
+                    max_turns: null,
+                    is_active: true,
+                    name_i18n: {},
+                    description_i18n: {},
+                    mission_prompt_i18n: {},
+                },
+                required: ['app_id', 'semantic_id', 'name', 'mission_prompt', 'outcome_schema'],
+                vocabularies: {},
+                notes: [
+                    'A preflight entry names a tool that must already hold a stored credential. A tool that runs in the page cannot be called before the session exists, and the write is refused. Create the tool with its credential first.',
+                    'A field the reviewer must have belongs in outcome_schema.required. An optional field is a field the model renames or drops.',
+                    'If the model must do something for the session to be valid, it is a precondition the runtime enforces through preflight, not a sentence in the mission.',
+                ],
+            };
+    }
+}
+export const TEMPLATE_KINDS = [
+    'view',
+    'control',
+    'form',
+    'tool',
+    'zone',
+    'action_plan',
+    'knowledge',
+    'session_template',
+];

package/dist/verify.js

@@ -61,7 +61,15 @@ async function checkWidgetBoots(url, storageStatePath) {
             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();
+    let browser;
+    try {
+        browser = await chromium.launch();
+    }
+    catch (error) {
+        return [
+            check('widget-boot', 'Widget boots on the page', 'skip', `A browser could not be launched: ${error instanceof Error ? error.message : String(error)}`, 'Run npx playwright install chromium, then re-run to check the browser half.'),
+        ];
+    }
     try {
         const context = await browser.newContext(storageStatePath ? { storageState: storageStatePath } : {});
         const page = await context.newPage();
@@ -93,6 +101,15 @@ async function checkWidgetBoots(url, storageStatePath) {
         }
         return checks;
     }
+    catch (error) {
+        // The browser half must not take the run down with it. Navigation is the
+        // most likely thing to fail here (the page is not up yet, DNS does not
+        // resolve, TLS is wrong), and that is exactly the moment the caller needs
+        // the four network checks that already ran.
+        return [
+            check('widget-boot', 'Widget boots on the page', 'fail', `The page could not be loaded in a browser: ${error instanceof Error ? error.message : String(error)}`, 'Confirm the URL is reachable from this machine, then re-run. The network checks above still apply.'),
+        ];
+    }
     finally {
         await browser.close();
     }

package/dist/version.d.ts

@@ -11,4 +11,4 @@
  * hand-synced numbers drift and the drift shows up as a client reporting a
  * version the server does not have.
  */
-export declare const SERVER_VERSION = "0.1.1";
+export declare const SERVER_VERSION = "0.3.0";

package/dist/version.js

@@ -11,4 +11,4 @@
  * hand-synced numbers drift and the drift shows up as a client reporting a
  * version the server does not have.
  */
-export const SERVER_VERSION = '0.1.1';
+export const SERVER_VERSION = '0.3.0';

package/examples/app.appilot.json

@@ -0,0 +1,212 @@
+{
+  "kind": "appilot.app-manifest",
+  "formatVersion": "1.0",
+  "app": {
+    "name": "Acme Booking",
+    "description": "The example manifest that ships with appilot-mcp. Copy it, change the names, keep the shape."
+  },
+  "domains": [
+    { "domain": "app.acme.com", "default_language": "en", "configured_languages": ["en", "de"] }
+  ],
+  "widgetKeys": [
+    { "name": "production", "allowedDomains": ["app.acme.com"] }
+  ],
+  "config": {
+    "kind": "appilot.config-bundle",
+    "formatVersion": "1.0",
+    "exportedAt": "2026-09-07T00:00:00.000Z",
+    "source": { "appId": 0, "appSlug": "acme-booking", "orgId": null },
+    "locales": ["en", "de"],
+    "entities": {
+      "views": [
+        {
+          "domain": "app.acme.com",
+          "path": "bookings",
+          "slug": "bookings",
+          "entry_path": "/bookings",
+          "is_active": true,
+          "source_locale": "en",
+          "translations": {
+            "en": { "name": "Bookings", "description": "The list of bookings and the form that creates one." },
+            "de": { "name": "Buchungen", "description": "Die Liste der Buchungen und das Formular, das eine anlegt." }
+          },
+          "detection_rules": [
+            { "priority": 10, "type": "path_prefix", "config": { "value": "/bookings" }, "is_active": true }
+          ]
+        }
+      ],
+      "controls": [
+        {
+          "semantic_id": "btn-create-booking",
+          "locator": "[data-testid=\"new-booking\"]",
+          "locator_type": "class_text",
+          "llm_hint": "Opens the booking form.",
+          "view_path": "bookings",
+          "scope": "view",
+          "prerequisites": null,
+          "is_active": true,
+          "form": null,
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "New booking", "description": "Opens the form that creates a booking." },
+            "de": { "label": "Neue Buchung", "description": "Öffnet das Formular, das eine Buchung anlegt." }
+          }
+        },
+        {
+          "semantic_id": "field-booking-date",
+          "locator": "booking-date",
+          "locator_type": "id",
+          "llm_hint": "The day the booking is for.",
+          "view_path": "bookings",
+          "scope": "view",
+          "prerequisites": null,
+          "is_active": true,
+          "form": { "form": "form-create-booking", "order": 1 },
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "Date", "description": "The day the booking is for." },
+            "de": { "label": "Datum", "description": "Der Tag, für den gebucht wird." }
+          }
+        },
+        {
+          "semantic_id": "submit-create-booking",
+          "locator": "[data-testid=\"save-booking\"]",
+          "locator_type": "class_text",
+          "llm_hint": "Saves the booking.",
+          "view_path": "bookings",
+          "scope": "view",
+          "prerequisites": null,
+          "is_active": true,
+          "form": null,
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "Save", "description": "Saves the booking." },
+            "de": { "label": "Speichern", "description": "Speichert die Buchung." }
+          }
+        }
+      ],
+      "forms": [
+        {
+          "semantic_id": "form-create-booking",
+          "domain": "app.acme.com",
+          "llm_hint": "Creates one booking.",
+          "view_paths": ["bookings"],
+          "required_fields": ["field-booking-date"],
+          "submit_control": "submit-create-booking",
+          "entry_control": "btn-create-booking",
+          "visibility_rules": null,
+          "field_defaults": null,
+          "prerequisites": null,
+          "is_active": true,
+          "source_locale": "en",
+          "translations": {
+            "en": { "label": "New booking", "description": "Creates one booking." },
+            "de": { "label": "Neue Buchung", "description": "Legt eine Buchung an." }
+          }
+        }
+      ],
+      "tools": [
+        {
+          "tool_name": "create_booking",
+          "view": null,
+          "parameters": {
+            "type": "object",
+            "properties": { "date": { "type": "string", "description": "ISO date the booking is for." } },
+            "required": ["date"]
+          },
+          "runtime_spec": {
+            "kind": "http_proxy",
+            "method": "POST",
+            "path_template": "/api/bookings",
+            "body_template": { "date": "{{date}}" }
+          },
+          "auth_header_name": "Authorization",
+          "source_locale": "en",
+          "translations": {
+            "en": { "title": "Create a booking", "description": "Use when the user wants to create a booking." },
+            "de": { "title": "Buchung anlegen", "description": "Verwenden, wenn die Person eine Buchung anlegen möchte." }
+          },
+          "parameter_descriptions": {
+            "en": { "date": "ISO date the booking is for." },
+            "de": { "date": "ISO-Datum, für das gebucht wird." }
+          }
+        }
+      ],
+      "zones": [],
+      "action_plans": [
+        {
+          "semantic_id": "plan-create-booking",
+          "sections": [
+            {
+              "view_path": "bookings",
+              "steps": [
+                "Open the form with [New booking]({{click:btn-create-booking}}).",
+                "Fill in [the booking form]({{form:form-create-booking}}).",
+                "Submit it with [Save]({{click:submit-create-booking}})."
+              ]
+            }
+          ],
+          "form_values": { "form-create-booking": { "fields": [] } },
+          "provenance": "registry",
+          "is_active": true,
+          "source_locale": "en",
+          "translations": {
+            "en": {
+              "name": "Create a booking",
+              "description": "Use when the user wants to create a booking.",
+              "step_narratives": null
+            },
+            "de": {
+              "name": "Buchung anlegen",
+              "description": "Verwenden, wenn die Person eine Buchung anlegen möchte.",
+              "step_narratives": [[
+                "Öffne das Formular mit [Neue Buchung]({{click:btn-create-booking}}).",
+                "Fülle [das Buchungsformular]({{form:form-create-booking}}) aus.",
+                "Sende es mit [Speichern]({{click:submit-create-booking}}) ab."
+              ]]
+            }
+          }
+        }
+      ],
+      "knowledge_content": [
+        {
+          "group": "booking-rules",
+          "scope": "app_global",
+          "url_pattern": null,
+          "domain": "app.acme.com",
+          "visibility": "internal",
+          "source": "manual",
+          "is_active": true,
+          "source_locale": "en",
+          "bodies": [
+            {
+              "language": "en",
+              "title": "What a booking is",
+              "description": "The rules and vocabulary behind a booking.",
+              "notes": null,
+              "general_info": "A booking reserves one resource for one day. Bookings are made by the account holder and cannot start in the past. A booking that has already started can be cancelled but not moved.\n\nThe procedure for creating one lives in the plan-create-booking action plan, not here."
+            },
+            {
+              "language": "de",
+              "title": "Was eine Buchung ist",
+              "description": "Die Regeln und Begriffe hinter einer Buchung.",
+              "notes": null,
+              "general_info": "Eine Buchung reserviert eine Ressource für einen Tag. Buchungen legt die Kontoinhaberin an, und sie können nicht in der Vergangenheit beginnen. Eine bereits begonnene Buchung lässt sich stornieren, aber nicht verschieben.\n\nDas Vorgehen zum Anlegen steht im Action Plan plan-create-booking, nicht hier."
+            }
+          ],
+          "views": [{ "domain": "app.acme.com", "path": "bookings", "priority": 10 }]
+        }
+      ],
+      "session_templates": []
+    },
+    "secretRefs": [
+      {
+        "entity": "tools",
+        "id": "create_booking",
+        "secret": "tool_auth:create_booking",
+        "status": "needs-reconnect",
+        "action": "Open the tool in the Backoffice and paste the credential. Secrets never travel in a bundle."
+      }
+    ]
+  }
+}