appilot-mcp 0.1.1 → 0.3.0

package/dist/client.js

@@ -9,6 +9,11 @@
  * defensively and never throw on a missing field. Field mapping is verified
  * against a live instance in the plan's Phase F.
  */
+/**
+ * Appilot's trilingual baseline, used only when the instance cannot say which
+ * languages an app actually claims to support.
+ */
+const DEFAULT_EXPECTED_LOCALES = ['de', 'en', 'es'];
 export class AppilotApiError extends Error {
     status;
     body;
@@ -19,8 +24,17 @@ export class AppilotApiError extends Error {
         this.name = 'AppilotApiError';
     }
 }
-/** Merge a base value + an `_i18n` override map into a single LocalizedText. */
-function fromBaseAndI18n(base, i18n) {
+/**
+ * Merge a base value + an `_i18n` override map into a single LocalizedText.
+ *
+ * The base column holds the text in the entity's SOURCE locale and `*_i18n`
+ * holds every other locale, so the source locale has to be indexed by name.
+ * Filing it under a synthetic 'base' key instead made the i18n lint report the
+ * source locale as missing on every entity that had any translation at all:
+ * a plan authored in `en` with `{ en: … }` and nothing else was told to
+ * "provide the name in en".
+ */
+function fromBaseAndI18n(base, i18n, sourceLocale) {
     const out = {};
     if (i18n && typeof i18n === 'object') {
         for (const [k, v] of Object.entries(i18n)) {
@@ -29,11 +43,17 @@ function fromBaseAndI18n(base, i18n) {
         }
     }
     if (typeof base === 'string' && base.length) {
-        // A base string has no locale of its own; expose it under a synthetic
-        // 'base' key AND leave declared locales as-is. The contract checks named
-        // locales, so we only surface base when nothing else exists.
-        if (Object.keys(out).length === 0)
+        const src = typeof sourceLocale === 'string' && sourceLocale ? sourceLocale : null;
+        // Never let the base overwrite an explicit per-locale value.
+        if (src) {
+            if (out[src] === undefined)
+                out[src] = base;
+        }
+        else if (Object.keys(out).length === 0) {
+            // An instance that does not record a source locale: the text is real
+            // but unattributable, so surface it without claiming a locale.
             out.base = base;
+        }
     }
     return out;
 }
@@ -55,8 +75,27 @@ function localized(entity, field) {
     const rows = entity.translations;
     if (Array.isArray(rows) && rows.length)
         return fromTranslationRows(rows, field);
-    return fromBaseAndI18n(entity[field], entity[`${field}_i18n`]);
+    return fromBaseAndI18n(entity[field], entity[`${field}_i18n`], entity.source_locale);
 }
+/**
+ * The eight configurable entities, and where each one is written.
+ *
+ * Session templates and zones are here for the same reason as the rest: an app
+ * whose activities are conversations, or whose pages need landmark regions, was
+ * not authorable from a conversation at all, because the only writer that
+ * reached them was a whole-bundle import.
+ */
+export const ENTITY_PATHS = {
+    view: '/views',
+    control: '/domain/controls',
+    form: '/domain/forms',
+    tool: '/domain/tools',
+    zone: '/domain/zones',
+    action_plan: '/domain/action-plans',
+    knowledge: '/knowledge/content',
+    session_template: '/domain/session-templates',
+};
+export const CONFIG_ENTITY_KINDS = Object.keys(ENTITY_PATHS);
 export class AppilotClient {
     conn;
     constructor(conn) {
@@ -77,8 +116,8 @@ export class AppilotClient {
         const text = await res.text();
         const body = text ? safeJson(text) : undefined;
         if (!res.ok) {
-            const message = body?.error ?? `${res.status} ${res.statusText}`;
-            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${message}`, res.status, body);
+            const credential = res.status === 401 || res.status === 403 ? ` ${credentialAdvice(!!this.conn.token)}` : '';
+            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${describeError(body, res)}${credential}`, res.status, body);
         }
         return body;
     }
@@ -104,21 +143,66 @@ export class AppilotClient {
     listKnowledge(appId) {
         return this.request(`/knowledge/content?app_id=${appId}`);
     }
+    listTools(appId) {
+        return this.request(`/domain/tools?app_id=${appId}`);
+    }
+    listZones(appId) {
+        return this.request(`/domain/zones?app_id=${appId}`);
+    }
+    /**
+     * The app's domains: which hostnames it serves, the languages each declares,
+     * and whether the hostname is verified. On the config surface, so a read-only
+     * credential can resolve the locales the configuration is expected to cover.
+     */
+    listAppDomains(appId) {
+        return this.request(`/config/domains?appId=${appId}`);
+    }
     // -- writes -------------------------------------------------------------
+    //
+    // One create, one update and one delete per configurable entity, so a
+    // conversation can author configuration without round-tripping the whole
+    // app through a ConfigBundle. The routes below were already reachable by a
+    // service token holding `config:write`; what was missing was this surface.
+    //
+    // The path per entity is the only thing that varies, so the table drives it.
+    // A hand-written method per entity is twenty-four near-identical bodies and a
+    // place for a typo to hide.
+    entityPath(kind, id) {
+        const base = ENTITY_PATHS[kind];
+        return id == null ? base : `${base}/${encodeURIComponent(id)}`;
+    }
+    createEntity(kind, body) {
+        return this.request(this.entityPath(kind), { method: 'POST', body: JSON.stringify(body) });
+    }
+    updateEntity(kind, id, body) {
+        return this.request(this.entityPath(kind, id), { method: 'PUT', body: JSON.stringify(body) });
+    }
+    deleteEntity(kind, id) {
+        return this.request(this.entityPath(kind, id), { method: 'DELETE' });
+    }
     updateActionPlan(id, body) {
-        return this.request(`/domain/action-plans/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('action_plan', id, body);
     }
     updateControl(id, body) {
-        return this.request(`/domain/controls/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('control', id, body);
     }
     createControl(body) {
-        return this.request(`/domain/controls`, { method: 'POST', body: JSON.stringify(body) });
+        return this.createEntity('control', body);
     }
     updateForm(id, body) {
-        return this.request(`/domain/forms/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('form', id, body);
     }
     updateKnowledge(id, body) {
-        return this.request(`/knowledge/content/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+        return this.updateEntity('knowledge', id, body);
+    }
+    // -- developer feedback -------------------------------------------------
+    // The one surface here that sends data OUT of the tenant. See server.ts for
+    // the consent rule and redaction.ts for what may not travel.
+    createDeveloperReport(body) {
+        return this.request('/developer-reports', { method: 'POST', body: JSON.stringify(body) });
+    }
+    listDeveloperReports(query) {
+        return this.request(`/developer-reports${query ? `?${query}` : ''}`);
     }
     /** Server-side non-persisting plan validation (echoes the runtime trust boundary). */
     validatePlan(appId, sections, formValues) {
@@ -134,6 +218,16 @@ export class AppilotClient {
     listProvisioned() {
         return this.request('/provision/apps');
     }
+    /**
+     * The org's widget keys, prefixes only.
+     *
+     * A caller that cannot see the keys it already minted asks for another every
+     * run, and each one is a live credential.
+     */
+    async listWidgetKeys() {
+        const body = await this.request('/provision/widget-keys');
+        return Array.isArray(body?.widgetKeys) ? body.widgetKeys : [];
+    }
     provisionApp(body) {
         return this.request('/provision/app', { method: 'POST', body: JSON.stringify(body) });
     }
@@ -141,9 +235,29 @@ export class AppilotClient {
      * Domain check: does this hostname resolve to a tenant? Public endpoint, so
      * it answers even for a read-only caller, which is what makes it usable as
      * the first probe of `verify_integration`.
+     *
+     * The endpoint takes a URL and derives the hostname itself; passing the bare
+     * hostname made the probe answer "URL is required" and report a warning about
+     * the tenant on every single run.
      */
     checkDomain(domain) {
-        return this.request(`/domain/check?domain=${encodeURIComponent(domain)}`);
+        const url = /^https?:\/\//i.test(domain) ? domain : `https://${domain}`;
+        return this.request(`/domain/check?url=${encodeURIComponent(url)}`);
+    }
+    /**
+     * The TXT record a domain needs, and where its verification stands.
+     *
+     * These two live on the apps router rather than under `/provision`, and that
+     * router authenticates an organization SESSION. A service token is refused
+     * there today, which is why `verify_domain` falls back to the provisioning
+     * dry run for the status and says plainly what it could not do.
+     */
+    domainVerification(domainId) {
+        return this.request(`/apps/domains/${domainId}/verification`);
+    }
+    /** Ask Appilot to look for the TXT record now. */
+    triggerDomainVerification(domainId) {
+        return this.request(`/apps/domains/${domainId}/verify`, { method: 'POST' });
     }
     /** Who this credential is: org, app narrowing, scopes. Never a secret. */
     whoami() {
@@ -164,27 +278,128 @@ export class AppilotClient {
     }
     /**
      * Read the app's content-model config and normalize it into a ConfigSnapshot.
-     * `expectedLocales` defaults to de/en/es (Appilot's trilingual baseline) but
-     * can be overridden per call once the domain's configured_languages are known.
+     *
+     * Two properties matter here and were both missing before.
+     *
+     * A failed read is a GAP, never an empty list. Swallowing the error made a
+     * refused knowledge read indistinguishable from an app with no knowledge, and
+     * every knowledge lint then passed on a configuration nobody had looked at.
+     *
+     * `expectedLocales` comes from the app's own domains when the caller does not
+     * say. The trilingual default is Appilot's baseline, not every customer's: a
+     * single-language app used to collect two medium i18n findings per entity for
+     * languages it had never claimed to support.
      */
-    async buildSnapshot(appId, expectedLocales = ['de', 'en', 'es']) {
-        const [plans, controls, forms, views, knowledge] = await Promise.all([
-            this.listActionPlans(appId).catch(() => []),
-            this.listControls(appId).catch(() => []),
-            this.listForms(appId).catch(() => []),
-            this.listViews(appId).catch(() => []),
-            this.listKnowledge(appId).catch(() => []),
+    async buildSnapshot(appId, expectedLocales) {
+        const gaps = [];
+        const read = async (entity, load, map) => {
+            try {
+                const rows = await load();
+                return Array.isArray(rows) ? rows.map(map) : [];
+            }
+            catch (err) {
+                gaps.push({ entity, reason: err instanceof Error ? err.message : String(err) });
+                return [];
+            }
+        };
+        const [plans, controls, forms, views, tools, zones, knowledge, locales] = await Promise.all([
+            read('actionPlans', () => this.listActionPlans(appId), mapActionPlan),
+            read('controls', () => this.listControls(appId), mapControl),
+            read('forms', () => this.listForms(appId), mapForm),
+            read('views', () => this.listViews(appId), mapView),
+            read('tools', () => this.listTools(appId), mapTool),
+            read('zones', () => this.listZones(appId), mapZone),
+            read('knowledge', () => this.listKnowledge(appId), mapKnowledge),
+            expectedLocales?.length ? Promise.resolve(expectedLocales) : this.resolveLocales(appId),
         ]);
+        // An empty knowledge list is the one read that can mean two things.
+        // `/knowledge/content` is an optional-auth route, so a missing or rejected
+        // bearer answers `200 []` instead of refusing, and from here that is
+        // indistinguishable from an app with no knowledge. Every knowledge lint
+        // then passes over a configuration nobody was allowed to look at, which is
+        // exactly the failure the `gaps` array exists to prevent.
+        if (knowledge.length === 0 && !gaps.some(g => g.entity === 'knowledge')) {
+            const refusal = await this.credentialRefusal();
+            if (refusal)
+                gaps.push({ entity: 'knowledge', reason: refusal });
+        }
         return {
-            expectedLocales,
-            views: views.map(mapView),
-            controls: controls.map(mapControl),
-            forms: forms.map(mapForm),
-            zones: [], // zones read per-domain; wired in Phase F once domain ids are resolved.
-            actionPlans: plans.map(mapActionPlan),
-            knowledge: knowledge.map(mapKnowledge),
+            expectedLocales: locales,
+            views,
+            controls,
+            forms,
+            tools,
+            zones,
+            actionPlans: plans,
+            knowledge,
+            ...(gaps.length ? { gaps } : {}),
         };
     }
+    /**
+     * Why an empty read should not be believed, or null when the credential is
+     * fine and the app genuinely has nothing.
+     *
+     * Only a 401 or a 403 counts. An instance too old to answer `whoami` at all
+     * says nothing about the token, and reporting a gap on that would be a
+     * confident false alarm on every on-premise deployment behind cloud.
+     */
+    async credentialRefusal() {
+        if (!this.conn.token) {
+            return `No service token is set, so the knowledge read was anonymous and answered an empty list rather than refusing. ${credentialAdvice(false)}`;
+        }
+        try {
+            await this.whoami();
+            return null;
+        }
+        catch (err) {
+            if (err instanceof AppilotApiError && (err.status === 401 || err.status === 403)) {
+                return `The knowledge read returned nothing and the credential failed its own self-check, so the empty result is not evidence of an empty knowledge base. ${credentialAdvice(true)}`;
+            }
+            return null;
+        }
+    }
+    /**
+     * Which locales this app's configuration is expected to cover: the union of
+     * its domains' configured languages. Falls back to the trilingual baseline
+     * when the instance cannot answer, which is the behaviour every caller had
+     * before and is still better than checking nothing.
+     */
+    async resolveLocales(appId) {
+        try {
+            const rows = await this.listAppDomains(appId);
+            const out = new Set();
+            for (const d of rows) {
+                const configured = d.configured_languages;
+                if (Array.isArray(configured)) {
+                    for (const l of configured)
+                        if (typeof l === 'string' && l)
+                            out.add(l);
+                }
+                const fallback = d.default_language;
+                if (typeof fallback === 'string' && fallback)
+                    out.add(fallback);
+            }
+            if (out.size)
+                return [...out].sort();
+        }
+        catch {
+            // Older instance, or a credential that cannot read domains.
+        }
+        return DEFAULT_EXPECTED_LOCALES;
+    }
+}
+/**
+ * What to do about a 401 or a 403, in the same voice as the offline errors.
+ *
+ * "Access denied. Token required." is the first thing a new developer meets and
+ * it names nothing: not the variable to set, not the screen the token comes
+ * from, not the preset to choose. The `APPILOT_BASE_URL` message next door does
+ * name all three, and it is the standard this one had to reach.
+ */
+function credentialAdvice(hasToken) {
+    return hasToken
+        ? 'The credential was rejected. Check it in the Backoffice under Service tokens: it may be revoked, expired, or scoped to another app. A token narrowed to one app is refused on every other app in the organization.'
+        : 'No credential is set. Put a service token in APPILOT_PAT in the MCP client environment and restart the client. Mint one in the Backoffice under Service tokens: "Inspect only" to read and audit, "Edit configuration" to write, "Set up integrations" to create apps, domains and widget keys.';
 }
 function safeJson(text) {
     try {
@@ -194,11 +409,54 @@ function safeJson(text) {
         return text;
     }
 }
+/**
+ * Render a backend error the way a model can act on it.
+ *
+ * The backend answers with `{ error, code, details, requestId }` (see
+ * docs/setup/logging-conventions.md). Reporting only `error` throws away the
+ * half that says what to fix: "Bundle failed structural validation" names no
+ * field, while `details.errors` names every path. Keep the rendering compact,
+ * because this lands in a conversation, and keep `requestId` so a support
+ * request can be matched to a server log line.
+ */
+function describeError(body, res) {
+    const b = (body ?? {});
+    if (typeof body !== 'object' || body === null) {
+        return typeof body === 'string' && body.trim() ? body.trim() : `${res.status} ${res.statusText}`;
+    }
+    const parts = [b.error ?? `${res.status} ${res.statusText}`];
+    if (b.code)
+        parts.push(`[${b.code}]`);
+    // The per-field issues. The backend produces four shapes and every one of
+    // them is the difference between "Form validation failed" and a refusal the
+    // caller can act on: envelope errors and Zod issues under `details`, the
+    // forms router's top-level `violations`, and the delete routes' `dependents`
+    // on a 409, which names exactly what still points at the entity.
+    const issues = (b.details?.errors ?? b.details?.issues ?? b.violations);
+    if (Array.isArray(issues) && issues.length) {
+        const shown = issues.slice(0, 20).map(i => typeof i === 'string' ? `  ${i}` : `  ${i.path || '(root)'}: ${i.message ?? ''}`.trimEnd());
+        if (issues.length > 20)
+            shown.push(`  and ${issues.length - 20} more`);
+        parts.push('\n' + shown.join('\n'));
+    }
+    else if (Array.isArray(b.dependents) && b.dependents.length) {
+        parts.push('\n  still referenced by: ' + JSON.stringify(b.dependents));
+    }
+    else if (b.details && Object.keys(b.details).length) {
+        parts.push(`\n  ${JSON.stringify(b.details)}`);
+    }
+    if (b.requestId)
+        parts.push(`\n  requestId ${b.requestId}`);
+    return parts.join(' ').replace(/ \n/g, '\n');
+}
 function mapView(v) {
     return { slug: v.slug, path: String(v.path ?? v.view_path ?? ''), name: localized(v, 'name') };
 }
 function mapControl(c) {
     return {
+        // The row id is what `update_entity` takes. Without it here the agent had
+        // no way to name the control it wanted to patch.
+        id: c.id != null ? String(c.id) : undefined,
         semantic_id: String(c.semantic_id ?? c.name ?? ''),
         locator_type: String(c.locator_type ?? c.locator_strategy ?? ''),
         locator: String(c.locator ?? c.locator_value ?? ''),
@@ -218,6 +476,7 @@ function mapForm(f) {
 function mapActionPlan(p) {
     const sections = p.sections ?? [];
     return {
+        id: p.id != null ? String(p.id) : undefined,
         semantic_id: String(p.semantic_id ?? ''),
         sections,
         form_values: p.form_values ?? {},
@@ -227,6 +486,22 @@ function mapActionPlan(p) {
         is_active: p.is_active !== false,
     };
 }
+function mapTool(t) {
+    const runtime = (t.runtime_spec ?? t.runtimeSpec);
+    return {
+        id: t.id != null ? String(t.id) : undefined,
+        tool_name: String(t.tool_name ?? t.name ?? ''),
+        kind: String(runtime?.kind ?? t.kind ?? ''),
+        view_path: t.view_path ?? null,
+        is_active: t.is_active !== false,
+    };
+}
+function mapZone(z) {
+    return {
+        id: z.id != null ? String(z.id) : undefined,
+        semantic_id: String(z.semantic_id ?? ''),
+    };
+}
 function mapKnowledge(k) {
     // A knowledge article read may return either a single localized row or a group
     // of language rows. Normalize both into a bodies[] list.

package/dist/config.d.ts

@@ -26,6 +26,17 @@ export interface AppilotConnection {
      * Defaults to stdio, which is the operator's own machine.
      */
     transport?: 'stdio' | 'http';
+    /**
+     * Scopes the CALLER was granted, when a grant sits in front of the credential.
+     *
+     * Only the remote transport has one: the person approved a specific set on the
+     * consent screen, and the service token sealed behind it may carry more. The
+     * backend enforces the token's scopes, not the grant's, so without this the
+     * consent screen was describing a limit nothing applied. Undefined on stdio,
+     * where the operator's own credential is the only authority and there is no
+     * grant to narrow it.
+     */
+    grantedScopes?: string[];
 }
 export declare function loadConnection(env?: NodeJS.ProcessEnv): AppilotConnection;
 /** Which transport the process serves. Local stdio unless asked otherwise. */
@@ -41,6 +52,9 @@ export declare function resolveTransport(argv?: string[], env?: NodeJS.ProcessEn
  * needs three things and no database.
  */
 export interface RemoteConfig {
+    handoffSecret?: string;
+    /** Trusted Backoffice origin for the connection help and brand assets. */
+    backofficeUrl?: string;
     /** Port to listen on. Cloud Run supplies PORT. */
     port: number;
     /** Public origin the clients reach, e.g. https://mcp.appilot.space. */

package/dist/config.js

@@ -67,8 +67,27 @@ export function loadRemoteConfig(env = process.env) {
     catch {
         throw new RemoteConfigError(`APPILOT_MCP_DOCS_URL is not a valid URL: ${rawDocs}`);
     }
+    const rawBackoffice = env.APPILOT_MCP_BACKOFFICE_URL?.trim() ||
+        (trimTrailingSlash(baseUrl) === 'https://api.appilot.space' ? 'https://backoffice.appilot.space' : undefined);
+    let backofficeUrl;
+    if (rawBackoffice) {
+        try {
+            const parsed = new URL(rawBackoffice);
+            if ((parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(parsed.hostname))) || parsed.username || parsed.password)
+                throw new Error();
+            backofficeUrl = parsed.origin;
+        }
+        catch {
+            throw new RemoteConfigError('APPILOT_MCP_BACKOFFICE_URL must be an HTTPS origin (localhost excepted).');
+        }
+    }
+    const handoffSecret = env.APPILOT_MCP_HANDOFF_SECRET?.trim();
+    if (handoffSecret && (handoffSecret.length < 32 || !backofficeUrl))
+        throw new RemoteConfigError('Session approval requires a 32-character handoff secret and a Backoffice origin.');
     return {
+        handoffSecret,
         port,
+        backofficeUrl,
         publicUrl,
         secret,
         allowedHosts: [publicUrl.host, ...extraHosts],

package/dist/contract/bundleSnapshot.js

@@ -52,6 +52,11 @@ export function snapshotFromBundle(entities, expectedLocales) {
         };
     });
     const zones = entities.zones.map(z => ({ semantic_id: z.semantic_id }));
+    const tools = entities.tools.map(t => ({
+        tool_name: t.tool_name,
+        kind: String(t.runtime_spec?.kind ?? ''),
+        view_path: t.view?.path ?? null,
+    }));
     const knowledge = entities.knowledge_content.map(k => ({
         id: k.group,
         scope: k.scope,
@@ -61,5 +66,7 @@ export function snapshotFromBundle(entities, expectedLocales) {
             title: b.title,
         })),
     }));
-    return { expectedLocales, views, controls, forms, zones, actionPlans, knowledge };
+    // A bundle is complete by construction (the envelope validator refuses a
+    // partial one), so there is never a gap on this path.
+    return { expectedLocales, views, controls, forms, tools, zones, actionPlans, knowledge };
 }

package/dist/contract/healthContract.d.ts

@@ -16,4 +16,4 @@ import type { ConfigSnapshot, HealthReport } from './types.js';
  * Run the full config health contract over a snapshot. Findings are returned
  * most-severe first, so the report reads like the manual audit.
  */
-export declare function runHealthContract(snap: ConfigSnapshot): HealthReport;
+export declare function runHealthContract(input: ConfigSnapshot): HealthReport;