@lila-modeler/mcp 0.0.0-stage → 1.0.0-beta.22

package/dist/json-patch.js

@@ -0,0 +1,174 @@
+/**
+ * JSON Patch (RFC 6902) mínimo para `patch_scenario` (LILA-055): `add`/`replace`/`remove`/`test`
+ * sobre objetos y arrays planos, con punteros RFC 6901. Sin `move`/`copy` (ponytail): son las dos
+ * operaciones que leen de una ubicación distinta a la que escriben, duplicarían la navegación, y
+ * ningún caso de uso de `patch_scenario` las necesita — documentado en `docs/MCP.md`.
+ *
+ * También arma el delta mínimo de un patch, para el modo "crear escenario con `extends`" de
+ * `patch_scenario`: la ruta de cada operación, anidada, con una clave borrada traducida a `null`
+ * (mismo borrado que usa `extends`, `docs/SCENARIO_FORMAT.md` § 6) y un array tocado en cualquier
+ * profundidad reemplazado entero (los arrays no se fusionan por índice en `extends`).
+ */
+const SUPPORTED_OPS = new Set(['add', 'replace', 'remove', 'test']);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * RFC 6901 no reserva ningún nombre de clave, pero en JavaScript `obj['__proto__'] = x` no crea
+ * una clave: escribe en el prototipo. Un patch con `/__proto__/loQueSea` contaminaba
+ * `Object.prototype` del **proceso servidor** entero —un servidor MCP por stdio es de vida larga—
+ * y dejaba colgada la llamada y todas las siguientes. `constructor` y `prototype` van a la misma
+ * lista: ningún escenario tiene claves así (`docs/SCENARIO_FORMAT.md` § 2).
+ */
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+function parsePointer(pointer) {
+    if (pointer === '')
+        throw new Error('json patch: la raíz del documento no se puede parchear.');
+    if (!pointer.startsWith('/'))
+        throw new Error(`json patch: puntero inválido: ${pointer}`);
+    return pointer
+        .slice(1)
+        .split('/')
+        .map((segment) => {
+        const key = segment.replaceAll('~1', '/').replaceAll('~0', '~');
+        if (FORBIDDEN_SEGMENTS.has(key)) {
+            throw new Error(`json patch: segmento prohibido "${key}" en ${pointer}: escribiría en el prototipo del objeto.`);
+        }
+        return key;
+    });
+}
+/**
+ * El puntero ya no puede nombrar esas claves, pero el `value` de un `add`/`replace` es JSON del
+ * cliente y `JSON.parse('{"__proto__":{…}}')` **sí** crea una clave propia: se escribía tal cual
+ * en el escenario guardado y `deepMerge` (LILA-204) se la comía en silencio al resolver el
+ * `extends`, dejando en disco un archivo con una clave que el motor ignora. Se rechaza igual que
+ * el segmento: aquí el patch es una orden explícita del agente, no un archivo heredado.
+ */
+function assertValueSinClavesDePrototipo(value, path) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertValueSinClavesDePrototipo(item, path);
+        return;
+    }
+    if (!isPlainObject(value))
+        return;
+    for (const [key, nested] of Object.entries(value)) {
+        if (FORBIDDEN_SEGMENTS.has(key)) {
+            throw new Error(`json patch: clave prohibida "${key}" en el value de ${path}: escribiría en el prototipo del objeto.`);
+        }
+        assertValueSinClavesDePrototipo(nested, path);
+    }
+}
+function child(container, key) {
+    if (Array.isArray(container))
+        return container[Number(key)];
+    if (isPlainObject(container))
+        return container[key];
+    return undefined;
+}
+function get(root, segments) {
+    let cursor = root;
+    for (const segment of segments)
+        cursor = child(cursor, segment);
+    return cursor;
+}
+/** Contenedor y clave del último segmento; lanza si algún tramo intermedio no existe. */
+function navigate(root, segments) {
+    let cursor = root;
+    for (const segment of segments.slice(0, -1)) {
+        cursor = child(cursor, segment);
+        if (cursor === undefined)
+            throw new Error(`json patch: no existe la ruta hasta "${segment}".`);
+    }
+    if (!isPlainObject(cursor) && !Array.isArray(cursor)) {
+        throw new Error('json patch: la ruta no llega a un objeto o array.');
+    }
+    return { parent: cursor, key: segments[segments.length - 1] ?? '' };
+}
+/** Aplica el patch a una copia profunda de `target`; nunca muta el original. */
+export function applyJsonPatch(target, patch) {
+    const root = structuredClone(target);
+    for (const op of patch) {
+        if (!SUPPORTED_OPS.has(op.op)) {
+            throw new Error(`json patch: operación no soportada: "${op.op}" (solo add/replace/remove/test; move/copy no están implementadas).`);
+        }
+        // RFC 6902 § 4: `add`, `replace` y `test` requieren `value`. Sin esto, un `add` sin `value`
+        // escribía `undefined`, que `JSON.stringify` descarta: un borrado silencioso en vez de error.
+        if (op.op !== 'remove' && op.value === undefined) {
+            throw new Error(`json patch: la operación "${op.op}" requiere "value" (${op.path}).`);
+        }
+        if (op.op !== 'remove')
+            assertValueSinClavesDePrototipo(op.value, op.path);
+        const segments = parsePointer(op.path);
+        if (op.op === 'test') {
+            const { parent, key } = navigate(root, segments);
+            if (JSON.stringify(child(parent, key)) !== JSON.stringify(op.value)) {
+                throw new Error(`json patch: test falló en ${op.path}.`);
+            }
+            continue;
+        }
+        const { parent, key } = navigate(root, segments);
+        if (Array.isArray(parent)) {
+            const index = key === '-' ? parent.length : Number(key);
+            if (!Number.isInteger(index) || index < 0 || index > parent.length) {
+                throw new Error(`json patch: índice inválido en ${op.path}.`);
+            }
+            if (op.op === 'add')
+                parent.splice(index, 0, op.value);
+            else if (index >= parent.length)
+                throw new Error(`json patch: no existe la ruta ${op.path}.`);
+            else if (op.op === 'replace')
+                parent[index] = op.value;
+            else
+                parent.splice(index, 1); // remove
+        }
+        else if (op.op === 'add') {
+            parent[key] = op.value;
+        }
+        else if (key in parent) {
+            if (op.op === 'replace')
+                parent[key] = op.value;
+            else
+                delete parent[key]; // remove
+        }
+        else {
+            throw new Error(`json patch: no existe la ruta ${op.path}.`);
+        }
+    }
+    return root;
+}
+/**
+ * Delta mínimo de un patch: solo las rutas que tocó alguna operación, leídas del documento **ya
+ * parcheado** (`patchedRoot`) para reflejar el estado final aunque varias operaciones compongan la
+ * misma ruta. Una clave que ya no existe en `patchedRoot` (un `remove`) se traduce a `null`.
+ */
+export function buildPatchDelta(patch, patchedRoot) {
+    const delta = {};
+    for (const op of patch) {
+        if (op.op === 'test' || !SUPPORTED_OPS.has(op.op))
+            continue;
+        const segments = parsePointer(op.path);
+        let deltaCursor = delta;
+        let patchedCursor = patchedRoot;
+        let stoppedAtArray = false;
+        for (const segment of segments.slice(0, -1)) {
+            const next = child(patchedCursor, segment);
+            if (Array.isArray(next)) {
+                deltaCursor[segment] = next; // los arrays se reemplazan enteros, nunca por índice (§ 6).
+                stoppedAtArray = true;
+                break;
+            }
+            if (!isPlainObject(deltaCursor[segment]))
+                deltaCursor[segment] = {};
+            deltaCursor = deltaCursor[segment];
+            patchedCursor = next;
+        }
+        if (stoppedAtArray)
+            continue;
+        const lastKey = segments[segments.length - 1];
+        const leaf = get(patchedRoot, segments);
+        deltaCursor[lastKey] = leaf === undefined ? null : leaf;
+    }
+    return delta;
+}
+//# sourceMappingURL=json-patch.js.map

package/dist/scenario-input.d.ts

@@ -0,0 +1,12 @@
+import { type Locale } from '@lila-modeler/engine/messages';
+import { type LilaProcess } from '@lila-modeler/engine/project-fs';
+import type { ResolvedScenario } from '@lila-modeler/engine/schema';
+export type ScenarioInput = string | Record<string, unknown>;
+/**
+ * With `lila` (the model is a `.lila`, #466), a string is a `.json` path or a scenario name of
+ * the process (`resolveScenarioArgument`), and an inline object is anchored inside the process's
+ * folder of the archive instead of the cwd: its `extends: "as-is.scenario.json"` names a scenario
+ * of the process, and a missing `model` means the process's `model.bpmn`.
+ */
+export declare function resolveScenarioInput(input: ScenarioInput, locale?: Locale, lila?: LilaProcess | undefined): ResolvedScenario;
+//# sourceMappingURL=scenario-input.d.ts.map

package/dist/scenario-input.js

@@ -0,0 +1,40 @@
+/**
+ * Resuelve el parámetro `scenario` de `run_simulation`/`compare_scenarios` (LILA-054): una ruta
+ * `.json` (relativa al cwd del proceso, con `extends` igual que la CLI) o el escenario ya resuelto
+ * como objeto inline.
+ *
+ * Un objeto inline se ancla a un archivo virtual `<escenario-inline>.json` en el cwd del proceso:
+ * si declara `extends`, esa referencia (y cualquier `model` relativo) se resuelve contra el cwd,
+ * igual que si el agente hubiera guardado el objeto ahí antes de pasarlo. `loadResolvedScenario`
+ * (de `@lila-modeler/engine/cli-shared`, LILA-054) hace la misma validación de escenario resuelto para
+ * ambos casos: no se duplica frente a la CLI.
+ */
+import { absolutePath, loadResolvedScenario, readJsonFile, resolveScenarioArgument, } from '@lila-modeler/engine/cli-shared';
+import { messages } from '@lila-modeler/engine/messages';
+import { lilaScenarioReader } from '@lila-modeler/engine/project-fs';
+/** Nombre del ancla virtual: no existe en disco, así que nunca debe salir en un mensaje. */
+const INLINE_FILE = '<escenario-inline>.json';
+/**
+ * With `lila` (the model is a `.lila`, #466), a string is a `.json` path or a scenario name of
+ * the process (`resolveScenarioArgument`), and an inline object is anchored inside the process's
+ * folder of the archive instead of the cwd: its `extends: "as-is.scenario.json"` names a scenario
+ * of the process, and a missing `model` means the process's `model.bpmn`.
+ */
+export function resolveScenarioInput(input, locale = 'en', lila) {
+    if (typeof input === 'string')
+        return resolveScenarioArgument(input, lila, locale).scenario;
+    const disk = (file) => readJsonFile(file, locale);
+    const virtualPath = lila === undefined ? absolutePath(INLINE_FILE) : `${lila.root}${INLINE_FILE}`;
+    const read = lila === undefined ? disk : lilaScenarioReader(lila, disk, locale);
+    const anchored = lila !== undefined && !('model' in input) ? { ...input, model: 'model.bpmn' } : input;
+    try {
+        return loadResolvedScenario(virtualPath, (file) => (file === virtualPath ? anchored : read(file)), locale);
+    }
+    catch (error) {
+        // Los mensajes de `loadResolvedScenario`/`resolveExtends` citan el archivo. El ancla no existe
+        // en disco: dejarla en el mensaje manda al agente a leer una ruta inventada.
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(detail.replaceAll(virtualPath, messages(locale).mcp.inlineScenario()));
+    }
+}
+//# sourceMappingURL=scenario-input.js.map

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { type Locale } from '@lila-modeler/engine/messages';
+import { McpServer } from '@modelcontextprotocol/server';
+/** Opciones de arranque comunes a `createServer` y `startStdioServer`. */
+export interface ServerOptions {
+    /** Idioma por defecto de las respuestas; cada llamada puede pedir otro con `locale`. */
+    locale?: Locale | undefined;
+}
+export declare function createServer(options?: ServerOptions): McpServer;
+/**
+ * Arranca el servidor sobre stdio. Lo usan el bin `lila-mcp` de este paquete y el subcomando
+ * `lila mcp` de `@lila-modeler/engine` (LILA-056), que lo carga con `import()` dinámico para no crear un
+ * ciclo de dependencia entre los dos paquetes. stdout es el transporte: nada más puede escribir ahí.
+ *
+ * Sin `locale`, el idioma sale del entorno (`LILA_LANG`, `LC_ALL`, `LC_MESSAGES`, `LANG`), la misma
+ * regla que la CLI: quien lo lanza desde `lila mcp` ya resolvió `--lang` y lo pasa explícito.
+ */
+export declare function startStdioServer(options?: ServerOptions): Promise<void>;
+//# sourceMappingURL=server.d.ts.map