appilot-mcp 0.1.0 → 0.2.1

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;

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;
@@ -87,13 +88,30 @@ function lintActionability(snap) {
         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
@@ -209,7 +227,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 +292,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 +351,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;