appilot-mcp 0.1.1 → 0.3.0

package/dist/contract/healthContract.js

@@ -13,7 +13,8 @@
  */
 import { validateActionPlanMarkers } from 'appilot-shared/utils';
 import { IDENTIFIER_KINDS } from 'appilot-shared/validation';
-const VALID_KB_SCOPES = new Set(['app_global', 'domain_global', 'page']);
+import { KNOWLEDGE_SCOPES } from 'appilot-shared/types';
+const VALID_KB_SCOPES = new Set(KNOWLEDGE_SCOPES);
 /** Extract every `{{kind:id}}` marker (with or without a `[label](...)` wrapper). */
 function extractMarkers(step) {
     const rx = /\{\{([a-z_]+):([^}]+)\}\}/g;
@@ -30,6 +31,19 @@ const CREATE_INTENT = /\b(create|add|new|update|edit|erstell|anleg|neu|hinzu|cre
 function localizedValues(text) {
     return Object.values(text).filter((v) => typeof v === 'string');
 }
+/**
+ * `form_values` as a record, whatever arrived.
+ *
+ * The snapshot type says it is one, and a hand-authored or scaffolded plan can
+ * still carry null or a string. Reading it defensively keeps a malformed bundle
+ * a finding rather than an exception thrown out of the whole audit.
+ */
+function authoredFormValues(plan) {
+    const raw = plan.form_values;
+    return raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : {};
+}
 // ---------------------------------------------------------------------------
 // Lint 1 — marker trust boundary (reuse appilot-shared).
 // ---------------------------------------------------------------------------
@@ -51,7 +65,7 @@ function lintMarkers(snap) {
             });
         }
         // form_values fields must belong to their form.
-        for (const [formId, entry] of Object.entries(plan.form_values)) {
+        for (const [formId, entry] of Object.entries(authoredFormValues(plan))) {
             if (!formIds.has(formId)) {
                 findings.push({
                     severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
@@ -59,8 +73,22 @@ function lintMarkers(snap) {
                 });
                 continue;
             }
+            // A malformed `form_values` entry is a FINDING, not a crash. The
+            // authored shape is `{ fields: [{ control_id, value }] }`, and a bundle
+            // carrying `{}` there used to take the whole contract down with
+            // "entry.fields is not iterable", so the one tool that could have named
+            // the defect answered with a stack trace instead.
+            const authored = entry;
+            if (!authored || !Array.isArray(authored.fields)) {
+                findings.push({
+                    severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
+                    message: `form_values["${formId}"] is not in the authored shape { fields: [{ control_id, value }] }.`,
+                    recommendation: 'Write an empty fields array when there are no authored defaults.',
+                });
+                continue;
+            }
             const fields = fieldsByForm.get(formId) ?? new Set();
-            for (const f of entry.fields) {
+            for (const f of authored.fields) {
                 if (!fields.has(f.control_id)) {
                     findings.push({
                         severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
@@ -83,17 +111,34 @@ function lintActionability(snap) {
         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 hasFormValues = Object.keys(authoredFormValues(plan)).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) {
+        // A plan that enters no value is not automatically inert. The defect
+        // this lint exists for is a plan that OPENS or FOCUSES something and
+        // stops, which is what "click the input, then nothing" looks like. A
+        // plan whose task is a decision, approve, reject, publish, archive,
+        // completes that task with the click itself, and there is no value to
+        // enter anywhere in it.
+        //
+        // So the test is what the clicks target. A click on a control that is
+        // not one of a form's own fields commits something. Only a plan with no
+        // commit at all, or one whose wording promises a create or an edit, is
+        // the defect.
+        const formFieldIds = new Set(snap.forms.flatMap(f => f.field_ids));
+        const commits = markers.some(m => m.kind === 'click' && !formFieldIds.has(m.id));
+        if (!entersValue && (looksLikeCreate || !commits)) {
             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.',
+                message: looksLikeCreate
+                    ? 'Plan enters no value: it has no {{form:…}} step, no set_value step, and empty form_values, so it opens an element and never completes the create or edit its description promises.'
+                    : 'Plan neither enters a value nor clicks anything outside a form\'s own fields, so it only opens or focuses an element and never completes the task.',
+                recommendation: looksLikeCreate
+                    ? 'Add a {{form:…}} step (or a set_value step) to enter the value, then a click step on the submit control to confirm.'
+                    : 'Add the step that commits the task: a click on the control that confirms it, or a {{form:…}} step followed by a submit.',
             });
         }
         // Submit-without-fill: clicks a form's submit but never fills that form
@@ -105,7 +150,7 @@ function lintActionability(snap) {
             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;
+                || (authoredFormValues(plan)[form.semantic_id]?.fields?.length ?? 0) > 0;
             if (!fillsForm) {
                 findings.push({
                     severity: 'high', category: 'actionability', entity: `action_plan:${plan.semantic_id}`,
@@ -209,7 +254,7 @@ function lintKnowledge(snap) {
             findings.push({
                 severity: 'high', category: 'kb-scope', entity,
                 message: `Invalid knowledge scope "${kb.scope}".`,
-                recommendation: 'Use one of app_global, domain_global, page.',
+                recommendation: `Use one of ${KNOWLEDGE_SCOPES.join(', ')}.`,
             });
         }
         const languages = new Set(kb.bodies.map(b => b.language));
@@ -274,14 +319,58 @@ function lintIdentifiers(snap) {
         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);
+    // A tool name is its own identifier kind: it reaches the model as a callable
+    // name, so it follows the tool_name rule rather than semantic_id. Medium, not
+    // high: an off-shape name still resolves at runtime, and a high finding would
+    // turn importing a working configuration that predates the rule into a 422.
+    for (const t of snap.tools) {
+        if (!IDENTIFIER_KINDS.tool_name.isValid(t.tool_name)) {
+            findings.push({
+                severity: 'medium', category: 'identifier', entity: `tool:${t.tool_name}`,
+                message: `Tool name "${t.tool_name}" is not a valid tool_name (${IDENTIFIER_KINDS.tool_name.rule}).`,
+                recommendation: `Rename it, for example ${IDENTIFIER_KINDS.tool_name.example}. The model calls the tool by this name.`,
+            });
+        }
+    }
     return findings;
 }
+// ---------------------------------------------------------------------------
+// Lint 7 — snapshot completeness.
+//
+// Reported as findings rather than thrown, because a partial snapshot is still
+// worth auditing. What must not happen is a partial snapshot reading as a clean
+// bill of health: every lint below an unreadable entity silently passes.
+// ---------------------------------------------------------------------------
+function lintGaps(snap) {
+    return (snap.gaps ?? []).map(g => ({
+        severity: 'high',
+        category: 'coverage',
+        entity: `snapshot:${g.entity}`,
+        message: `${g.entity} could not be read, so no ${g.entity} lint ran: ${g.reason}`,
+        recommendation: 'Fix the access problem and re-run. Treat every finding in this report as incomplete until this line is gone.',
+    }));
+}
 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) {
+export function runHealthContract(input) {
+    // Normalise once. A snapshot reaches this function from three producers (the
+    // live-API client, the bundle adapter, the backend import path) and every lint
+    // below iterates these arrays without a guard; one producer omitting one of
+    // them would otherwise crash the audit instead of reporting on it.
+    const snap = {
+        ...input,
+        expectedLocales: input.expectedLocales ?? [],
+        views: input.views ?? [],
+        controls: input.controls ?? [],
+        forms: input.forms ?? [],
+        tools: input.tools ?? [],
+        zones: input.zones ?? [],
+        actionPlans: input.actionPlans ?? [],
+        knowledge: input.knowledge ?? [],
+    };
     const findings = [
         ...lintMarkers(snap),
         ...lintActionability(snap),
@@ -289,6 +378,7 @@ export function runHealthContract(snap) {
         ...lintI18n(snap),
         ...lintKnowledge(snap),
         ...lintIdentifiers(snap),
+        ...lintGaps(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)

package/dist/contract/types.d.ts

@@ -7,7 +7,7 @@
  * 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 type FindingCategory = 'markers' | 'actionability' | 'selector-stability' | 'i18n-coverage' | 'kb-scope' | 'kb-procedure' | 'kb-hygiene' | 'identifier' | 'coverage';
 export interface Finding {
     severity: Severity;
     category: FindingCategory;
@@ -21,6 +21,9 @@ export interface Finding {
 /** A per-locale text map, e.g. `{ de: 'Neuer Ordner', en: 'New folder' }`. */
 export type LocalizedText = Record<string, string | undefined>;
 export interface ControlSnapshot {
+    /** Row id, when the snapshot came from the live API. Absent from a bundle,
+     *  which is keyed semantically. `update_control` needs it. */
+    id?: string;
     semantic_id: string;
     locator_type: string;
     locator: string;
@@ -34,6 +37,8 @@ export interface FormSnapshot {
     entry_control_id?: string | null;
 }
 export interface ActionPlanSnapshot {
+    /** Row id, when the snapshot came from the live API. See ControlSnapshot.id. */
+    id?: string;
     semantic_id: string;
     sections: Array<{
         view_path?: string;
@@ -52,9 +57,25 @@ export interface ActionPlanSnapshot {
     is_active?: boolean;
 }
 export interface ZoneSnapshot {
+    id?: string;
     semantic_id: string;
 }
+/**
+ * A tool as the agent needs to reason about it: what it is called, what kind of
+ * runtime backs it, and whether it is bound to a view. Not the full definition;
+ * `export_config` carries that.
+ */
+export interface ToolSnapshot {
+    id?: string;
+    tool_name: string;
+    /** `http_proxy`, `client_action`, … Empty when the instance does not say. */
+    kind: string;
+    view_path?: string | null;
+    is_active?: boolean;
+}
 export interface KnowledgeSnapshot {
+    /** Row id on the live-API path (what `update_knowledge` takes), the
+     *  translation group on the bundle path. */
     id: string | number;
     scope: string;
     /** Body text per language row (knowledge_content is one row per language). */
@@ -69,15 +90,30 @@ export interface ViewSnapshot {
     path: string;
     name: LocalizedText;
 }
+/**
+ * An entity the snapshot could not read, and why.
+ *
+ * A snapshot with an empty `knowledge` array and a snapshot whose knowledge read
+ * was refused look identical, and the second one silently turns every knowledge
+ * lint into a pass. Recording the failure is what lets `read_config` and
+ * `validate_config` say "I could not see this" instead of "this is fine".
+ */
+export interface SnapshotGap {
+    entity: 'views' | 'controls' | 'forms' | 'tools' | 'zones' | 'actionPlans' | 'knowledge';
+    reason: string;
+}
 export interface ConfigSnapshot {
     /** Locales the config is expected to cover, e.g. ['de','en','es']. */
     expectedLocales: string[];
     views: ViewSnapshot[];
     controls: ControlSnapshot[];
     forms: FormSnapshot[];
+    tools: ToolSnapshot[];
     actionPlans: ActionPlanSnapshot[];
     zones: ZoneSnapshot[];
     knowledge: KnowledgeSnapshot[];
+    /** Entities that could not be read. Empty on a complete snapshot. */
+    gaps?: SnapshotGap[];
 }
 export interface HealthReport {
     ok: boolean;