appilot-mcp 0.0.1 → 0.1.0

package/dist/contract/healthContract.js

@@ -0,0 +1,297 @@
+/**
+ * The Appilot config health contract.
+ *
+ * A set of pure lints over a `ConfigSnapshot` that encode what a WELL-FORMED
+ * content-model configuration looks like. Every lint traces to a real failure
+ * mode observed when apps are hand-authored (see the BeKnow `create-task`
+ * audit). The marker + identifier checks REUSE the canonical validators from
+ * `appilot-shared` so the contract can never drift from the runtime:
+ *   - `validateActionPlanMarkers` (the same trust boundary the backend applies)
+ *   - `IDENTIFIER_KINDS` (the single source of truth for identifier shape)
+ *
+ * Contract docs: docs/content-model/config-health-contract.md.
+ */
+import { validateActionPlanMarkers } from 'appilot-shared/utils';
+import { IDENTIFIER_KINDS } from 'appilot-shared/validation';
+const VALID_KB_SCOPES = new Set(['app_global', 'domain_global', 'page']);
+/** Extract every `{{kind:id}}` marker (with or without a `[label](...)` wrapper). */
+function extractMarkers(step) {
+    const rx = /\{\{([a-z_]+):([^}]+)\}\}/g;
+    const out = [];
+    let m;
+    while ((m = rx.exec(step)) !== null)
+        out.push({ kind: m[1], id: m[2].trim() });
+    return out;
+}
+function planMarkers(plan) {
+    return plan.sections.flatMap(s => s.steps.flatMap(extractMarkers));
+}
+const CREATE_INTENT = /\b(create|add|new|update|edit|erstell|anleg|neu|hinzu|crear|nuev[ao]|añad|editar|actualiz)/i;
+function localizedValues(text) {
+    return Object.values(text).filter((v) => typeof v === 'string');
+}
+// ---------------------------------------------------------------------------
+// Lint 1 — marker trust boundary (reuse appilot-shared).
+// ---------------------------------------------------------------------------
+function lintMarkers(snap) {
+    const controlIds = new Set(snap.controls.map(c => c.semantic_id));
+    const formIds = new Set(snap.forms.map(f => f.semantic_id));
+    const zoneIds = new Set(snap.zones.map(z => z.semantic_id));
+    const fieldsByForm = new Map(snap.forms.map(f => [f.semantic_id, new Set(f.field_ids)]));
+    const findings = [];
+    for (const plan of snap.actionPlans) {
+        const result = validateActionPlanMarkers(plan.sections, { controlIds, formIds, zoneIds });
+        for (const error of result.errors) {
+            findings.push({
+                severity: 'high',
+                category: 'markers',
+                entity: `action_plan:${plan.semantic_id}`,
+                message: error,
+                recommendation: 'Each step needs exactly one executable marker resolving to a known control/form; values never go in the marker.',
+            });
+        }
+        // form_values fields must belong to their form.
+        for (const [formId, entry] of Object.entries(plan.form_values)) {
+            if (!formIds.has(formId)) {
+                findings.push({
+                    severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
+                    message: `form_values references unknown form "${formId}".`,
+                });
+                continue;
+            }
+            const fields = fieldsByForm.get(formId) ?? new Set();
+            for (const f of entry.fields) {
+                if (!fields.has(f.control_id)) {
+                    findings.push({
+                        severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
+                        message: `form_values field "${f.control_id}" does not belong to form "${formId}".`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Lint 2 — actionability: a plan must actually enter a value and submit, not
+// just open/focus an element (the core create-task defect).
+// ---------------------------------------------------------------------------
+function lintActionability(snap) {
+    const findings = [];
+    const submitControlIds = new Set(snap.forms.map(f => f.submit_control_id).filter((x) => !!x));
+    for (const plan of snap.actionPlans) {
+        const markers = planMarkers(plan);
+        const hasFormStep = markers.some(m => m.kind === 'form');
+        const hasSetValue = markers.some(m => m.kind === 'set_value' || m.kind === 'select');
+        const hasFormValues = Object.keys(plan.form_values).length > 0;
+        const entersValue = hasFormStep || hasSetValue || hasFormValues;
+        const looksLikeCreate = localizedValues({ ...plan.name, ...plan.description }).some(v => CREATE_INTENT.test(v))
+            || CREATE_INTENT.test(plan.semantic_id);
+        if (!entersValue) {
+            findings.push({
+                severity: looksLikeCreate ? 'critical' : 'high',
+                category: 'actionability',
+                entity: `action_plan:${plan.semantic_id}`,
+                message: 'Plan enters no value: it has no {{form:…}} step, no set_value step, and empty form_values, so it only opens/focuses an element and never completes the task.',
+                recommendation: 'Add a {{form:…}} step (or a set_value step) to enter the value, then a click step on the submit control to confirm.',
+            });
+        }
+        // Submit-without-fill: clicks a form's submit but never fills that form
+        // (ports warnOnUnfilledFormSubmit).
+        for (const form of snap.forms) {
+            if (!form.submit_control_id)
+                continue;
+            const clicksSubmit = markers.some(m => m.kind === 'click' && m.id === form.submit_control_id);
+            if (!clicksSubmit)
+                continue;
+            const fillsForm = markers.some(m => m.kind === 'form' && m.id === form.semantic_id)
+                || (plan.form_values[form.semantic_id]?.fields?.length ?? 0) > 0;
+            if (!fillsForm) {
+                findings.push({
+                    severity: 'high', category: 'actionability', entity: `action_plan:${plan.semantic_id}`,
+                    message: `Plan clicks the submit control "${form.submit_control_id}" of form "${form.semantic_id}" without a fill step, so it submits an empty form.`,
+                    recommendation: `Add a {{form:${form.semantic_id}}} step before the submit.`,
+                });
+            }
+        }
+        void submitControlIds;
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Lint 3 — selector stability: reject auto-generated / positional locators.
+// ---------------------------------------------------------------------------
+const UNSTABLE_LOCATOR_PATTERNS = [
+    { rx: /\b[a-z-]*vue-\d+/i, why: 'a framework-generated Vue component id (changes across renders)' },
+    { rx: /\b(?:mui|radix|headlessui|el|ember|ext)-[a-z]*-?\d{2,}/i, why: 'a framework-generated ephemeral id' },
+    { rx: /:nth-(?:child|of-type)\(/i, why: 'a positional selector (breaks when siblings change)' },
+    { rx: /^#?[a-f0-9]{8,}$/i, why: 'a random hash id' },
+];
+function lintSelectorStability(snap) {
+    const findings = [];
+    for (const c of snap.controls) {
+        const match = UNSTABLE_LOCATOR_PATTERNS.find(p => p.rx.test(c.locator));
+        if (match) {
+            findings.push({
+                severity: 'high',
+                category: 'selector-stability',
+                entity: `control:${c.semantic_id}`,
+                message: `Locator "${c.locator}" is ${match.why}.`,
+                recommendation: 'Target a stable attribute (data-cy/data-test/aria-label/role/placeholder) and list one or two fallbacks, e.g. use locator_type class_text with a comma-separated selector list.',
+            });
+        }
+        // scope=global must not carry a view_path.
+        if (c.scope === 'global' && c.view_path) {
+            findings.push({
+                severity: 'medium', category: 'selector-stability', entity: `control:${c.semantic_id}`,
+                message: 'Control has scope "global" but also a view_path; global controls must not be view-scoped.',
+                recommendation: 'Clear view_path, or change scope to view.',
+            });
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Lint 4 — i18n coverage for user-facing translatable fields.
+// ---------------------------------------------------------------------------
+function checkLocaleCoverage(text, expected, entity, field, findings) {
+    for (const locale of expected) {
+        const value = text[locale];
+        if (value === undefined || value === null) {
+            findings.push({
+                severity: 'medium', category: 'i18n-coverage', entity,
+                message: `Missing ${locale} translation for ${field}.`,
+                recommendation: `Provide the ${field} in ${expected.join('/')}.`,
+            });
+        }
+        else if (value.trim() === '') {
+            findings.push({
+                severity: 'medium', category: 'i18n-coverage', entity,
+                message: `Empty ${locale} translation for ${field}.`,
+            });
+        }
+    }
+}
+function lintI18n(snap) {
+    const findings = [];
+    for (const plan of snap.actionPlans) {
+        const entity = `action_plan:${plan.semantic_id}`;
+        checkLocaleCoverage(plan.name, snap.expectedLocales, entity, 'name', findings);
+        checkLocaleCoverage(plan.description, snap.expectedLocales, entity, 'description', findings);
+        if (plan.step_narratives) {
+            for (const locale of snap.expectedLocales) {
+                const variants = plan.step_narratives[locale];
+                if (!variants || variants.length === 0) {
+                    findings.push({
+                        severity: 'low', category: 'i18n-coverage', entity,
+                        message: `Missing ${locale} step narratives.`,
+                    });
+                }
+            }
+        }
+    }
+    for (const v of snap.views) {
+        checkLocaleCoverage(v.name, snap.expectedLocales, `view:${v.path}`, 'name', findings);
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Lint 5 — knowledge: scope validity, language coverage, procedure-in-KB,
+// leftover chatbot hygiene.
+// ---------------------------------------------------------------------------
+const CHATBOT_META = /\b(soll ich|möchtest du|dann kann ich|entsprechend anpassen|let me know|i can adjust|feel free to|as an ai|as a language model|espero que|si quieres puedo|puedo ajustar)\b/i;
+const PROCEDURE_HINT = /(^|\n)\s*(\d+[.)]\s+\S.*){3,}|<ol[\s>]|(?:^|\n)\s*(?:schritt|step|paso)\s*\d/im;
+function lintKnowledge(snap) {
+    const findings = [];
+    for (const kb of snap.knowledge) {
+        const entity = `knowledge:${kb.id}`;
+        if (!VALID_KB_SCOPES.has(kb.scope)) {
+            findings.push({
+                severity: 'high', category: 'kb-scope', entity,
+                message: `Invalid knowledge scope "${kb.scope}".`,
+                recommendation: 'Use one of app_global, domain_global, page.',
+            });
+        }
+        const languages = new Set(kb.bodies.map(b => b.language));
+        for (const locale of snap.expectedLocales) {
+            if (!languages.has(locale)) {
+                findings.push({
+                    severity: 'medium', category: 'kb-scope', entity,
+                    message: `Knowledge article has no ${locale} language row.`,
+                    recommendation: `Add a ${locale} translation (retrieval falls back, but coverage should be complete).`,
+                });
+            }
+        }
+        for (const body of kb.bodies) {
+            if (CHATBOT_META.test(body.text)) {
+                findings.push({
+                    severity: 'medium', category: 'kb-hygiene', entity,
+                    message: `The ${body.language} body contains a chatbot meta-sentence (conversational filler pasted from an assistant).`,
+                    recommendation: 'Remove offers to "adjust the text" and other conversational filler; KB is reference prose, not a chat reply.',
+                });
+            }
+            if (PROCEDURE_HINT.test(body.text)) {
+                findings.push({
+                    severity: 'medium', category: 'kb-procedure', entity,
+                    message: `The ${body.language} body reads like a step-by-step procedure.`,
+                    recommendation: 'A procedure belongs in a curated Action Plan (adopt_plan), not KB. KB is for meaning (workflows, rules, terminology).',
+                });
+            }
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Lint 6 — identifier hygiene (reuse IDENTIFIER_KINDS).
+// ---------------------------------------------------------------------------
+function lintIdentifier(id, entity, findings) {
+    if (!IDENTIFIER_KINDS.semantic_id.isValid(id)) {
+        findings.push({
+            severity: 'high', category: 'identifier', entity,
+            message: `Identifier "${id}" is not a valid semantic_id (${IDENTIFIER_KINDS.semantic_id.rule}).`,
+            recommendation: `Example: ${IDENTIFIER_KINDS.semantic_id.example}.`,
+        });
+        return;
+    }
+    // Slugified-UI-label heuristic: many segments + long => likely derived from a
+    // translated label rather than a purpose-named English identifier.
+    const segments = id.split(/[-_]/).filter(Boolean);
+    if (segments.length >= 4 && id.length >= 24) {
+        findings.push({
+            severity: 'low', category: 'identifier', entity,
+            message: `Identifier "${id}" looks like a slugified UI label (${segments.length} segments).`,
+            recommendation: 'Prefer a short English noun-qualifier, e.g. field-new-task or btn-task-submit; identifiers should survive label/translation changes.',
+        });
+    }
+}
+function lintIdentifiers(snap) {
+    const findings = [];
+    for (const c of snap.controls)
+        lintIdentifier(c.semantic_id, `control:${c.semantic_id}`, findings);
+    for (const f of snap.forms)
+        lintIdentifier(f.semantic_id, `form:${f.semantic_id}`, findings);
+    for (const z of snap.zones)
+        lintIdentifier(z.semantic_id, `zone:${z.semantic_id}`, findings);
+    for (const p of snap.actionPlans)
+        lintIdentifier(p.semantic_id, `action_plan:${p.semantic_id}`, findings);
+    return findings;
+}
+const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+/**
+ * Run the full config health contract over a snapshot. Findings are returned
+ * most-severe first, so the report reads like the manual audit.
+ */
+export function runHealthContract(snap) {
+    const findings = [
+        ...lintMarkers(snap),
+        ...lintActionability(snap),
+        ...lintSelectorStability(snap),
+        ...lintI18n(snap),
+        ...lintKnowledge(snap),
+        ...lintIdentifiers(snap),
+    ].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+    const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return { ok: counts.critical === 0 && counts.high === 0, counts, findings };
+}

package/dist/contract/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export { runHealthContract } from './healthContract.js';
+export { snapshotFromBundle } from './bundleSnapshot.js';

package/dist/contract/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export { runHealthContract } from './healthContract.js';
+export { snapshotFromBundle } from './bundleSnapshot.js';

package/dist/contract/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Types for the Appilot config health contract.
+ *
+ * A `ConfigSnapshot` is a normalized, transport-agnostic view of one app's
+ * content-model configuration. The MCP client maps live API responses (or a
+ * pasted export) into this shape; the contract lints run purely over it, so the
+ * same validator works online, offline (air-gapped), and in unit fixtures.
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low';
+export type FindingCategory = 'markers' | 'actionability' | 'selector-stability' | 'i18n-coverage' | 'kb-scope' | 'kb-procedure' | 'kb-hygiene' | 'identifier';
+export interface Finding {
+    severity: Severity;
+    category: FindingCategory;
+    /** Stable entity handle, e.g. `action_plan:create-task` or `control:btn-new`. */
+    entity: string;
+    /** One-sentence statement of the defect. */
+    message: string;
+    /** Concrete, actionable fix. */
+    recommendation?: string;
+}
+/** A per-locale text map, e.g. `{ de: 'Neuer Ordner', en: 'New folder' }`. */
+export type LocalizedText = Record<string, string | undefined>;
+export interface ControlSnapshot {
+    semantic_id: string;
+    locator_type: string;
+    locator: string;
+    view_path?: string | null;
+    scope?: string | null;
+}
+export interface FormSnapshot {
+    semantic_id: string;
+    field_ids: string[];
+    submit_control_id?: string | null;
+    entry_control_id?: string | null;
+}
+export interface ActionPlanSnapshot {
+    semantic_id: string;
+    sections: Array<{
+        view_path?: string;
+        steps: string[];
+    }>;
+    form_values: Record<string, {
+        fields: Array<{
+            control_id: string;
+            value: string;
+        }>;
+    }>;
+    name: LocalizedText;
+    description: LocalizedText;
+    /** locale -> array of step-narrative variants (each variant an array of step strings). */
+    step_narratives?: Record<string, string[][]>;
+    is_active?: boolean;
+}
+export interface ZoneSnapshot {
+    semantic_id: string;
+}
+export interface KnowledgeSnapshot {
+    id: string | number;
+    scope: string;
+    /** Body text per language row (knowledge_content is one row per language). */
+    bodies: Array<{
+        language: string;
+        text: string;
+        title?: string;
+    }>;
+}
+export interface ViewSnapshot {
+    slug?: string;
+    path: string;
+    name: LocalizedText;
+}
+export interface ConfigSnapshot {
+    /** Locales the config is expected to cover, e.g. ['de','en','es']. */
+    expectedLocales: string[];
+    views: ViewSnapshot[];
+    controls: ControlSnapshot[];
+    forms: FormSnapshot[];
+    actionPlans: ActionPlanSnapshot[];
+    zones: ZoneSnapshot[];
+    knowledge: KnowledgeSnapshot[];
+}
+export interface HealthReport {
+    ok: boolean;
+    counts: Record<Severity, number>;
+    findings: Finding[];
+}

package/dist/contract/types.js

@@ -0,0 +1,9 @@
+/**
+ * Types for the Appilot config health contract.
+ *
+ * A `ConfigSnapshot` is a normalized, transport-agnostic view of one app's
+ * content-model configuration. The MCP client maps live API responses (or a
+ * pasted export) into this shape; the contract lints run purely over it, so the
+ * same validator works online, offline (air-gapped), and in unit fixtures.
+ */
+export {};