@lightward/mechanic-mcp 0.1.3 → 0.1.4

package/dist/data/manifest.json

@@ -1,9 +1,9 @@
 {
-  "builtAt": "2025-12-04T22:15:41.397Z",
+  "builtAt": "2026-03-29T04:00:47.709Z",
   "counts": {
-    "docs": 314,
-    "tasks": 357,
-    "total": 671
+    "docs": 332,
+    "tasks": 360,
+    "total": 692
   },
   "sources": {
     "docsPath": "/Users/msodomsky/dev/mechanic-docs",

package/dist/task-dev.js

@@ -0,0 +1,631 @@
+// Task development helpers: lint + preview simulation.
+// These utilities are deliberately conservative and only cover a small subset
+// of Mechanic's runtime to offer quick, offline feedback.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Liquid } from 'liquidjs';
+import { inlineTaskSchema, lintTaskOutputSchema, previewTaskOutputSchema } from './schemas.js';
+const PREVIEW_FIXTURES = {
+    'shopify/orders/create': {
+        id: 'gid://shopify/Order/1234567890',
+        name: '#1001',
+        email: 'customer@example.com',
+        source_name: 'web',
+        note_attributes: [],
+        line_items: [
+            {
+                id: 'gid://shopify/LineItem/123',
+                sku: 'SKU-123',
+                quantity: 1,
+                price_set: { shop_money: { amount: '12.00', currency_code: 'USD' } },
+            },
+        ],
+    },
+    'shopify/customers/create': {
+        id: 'gid://shopify/Customer/1234567890',
+        email: 'customer@example.com',
+        first_name: 'Ada',
+        last_name: 'Lovelace',
+        tags: ['vip'],
+        note: 'Preview payload',
+    },
+    'user/event/preview': {
+        message: 'Hello from a preview event',
+    },
+};
+const ALLOWED_ACTIONS = new Set([
+    'echo',
+    'email',
+    'event',
+    'shopify',
+    'cache',
+    'files',
+    'ftp',
+    'http',
+    'slack',
+    'google',
+    'google_drive',
+    'google_sheets',
+    'flow',
+    'report_toaster',
+    'airtable',
+    'oauth2',
+    'general_o_auth2',
+]);
+const DEFAULT_CUSTOM_TOPIC = 'user/event/preview';
+const BASE_LIQUID_TAGS = new Set([
+    'assign',
+    'capture',
+    'increment',
+    'decrement',
+    'if',
+    'elsif',
+    'else',
+    'unless',
+    'case',
+    'when',
+    'endcase',
+    'endif',
+    'endunless',
+    'for',
+    'endfor',
+    'cycle',
+    'tablerow',
+    'endtablerow',
+    'break',
+    'continue',
+    'comment',
+    'endcomment',
+    'raw',
+    'endraw',
+    'include',
+    'render',
+    'echo',
+    'liquid',
+]);
+const MECHANIC_TAGS = new Set(['action', 'log', 'error', 'permissions']);
+const BASE_LIQUID_FILTERS = new Set([
+    'abs',
+    'append',
+    'at_least',
+    'at_most',
+    'capitalize',
+    'ceil',
+    'compact',
+    'concat',
+    'date',
+    'default',
+    'divided_by',
+    'downcase',
+    'escape',
+    'escape_once',
+    'first',
+    'floor',
+    'join',
+    'last',
+    'lstrip',
+    'map',
+    'minus',
+    'modulo',
+    'newline_to_br',
+    'plus',
+    'prepend',
+    'remove',
+    'remove_first',
+    'replace',
+    'replace_first',
+    'reverse',
+    'round',
+    'size',
+    'slice',
+    'sort',
+    'sort_natural',
+    'split',
+    'strip',
+    'strip_html',
+    'strip_newlines',
+    'times',
+    'truncate',
+    'truncatewords',
+    'uniq',
+    'upcase',
+    'url_decode',
+    'url_encode',
+]);
+const MECHANIC_FILTERS = new Set([
+    'array',
+    'base64',
+    'browser',
+    'compact',
+    'compress',
+    'csv',
+    'currency',
+    'date',
+    'digest',
+    'e164',
+    'graphql',
+    'hash',
+    'img_url',
+    'json',
+    'regexp',
+    'money',
+    'newline',
+    'shop',
+    'shopify',
+    'sort',
+    'string',
+    'slice',
+    'tag',
+    'tags',
+    'where',
+    'xml',
+]);
+function loadDynamicSamples() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        process.env.MECHANIC_EVENT_SAMPLES_PATH,
+        // when running from repo root
+        path.resolve(here, '..', 'mechanic-api', 'app', 'lib', 'mechanic', 'event_topics', 'data_samples'),
+        // when running from built dist/
+        path.resolve(here, '..', 'data', 'event_samples'),
+        // when running from project root in dev
+        path.resolve(process.cwd(), 'dist', 'data', 'event_samples'),
+    ].filter(Boolean);
+    const merged = {};
+    for (const candidate of candidates) {
+        try {
+            if (!fs.existsSync(candidate))
+                continue;
+            const files = fs.readdirSync(candidate, { withFileTypes: true });
+            files.forEach((dirent) => {
+                const subpath = path.join(candidate, dirent.name);
+                if (dirent.isDirectory()) {
+                    const subFiles = fs.readdirSync(subpath, { withFileTypes: true });
+                    subFiles.forEach((subDirent) => {
+                        const nestedPath = path.join(subpath, subDirent.name);
+                        if (subDirent.isDirectory()) {
+                            fs.readdirSync(nestedPath, { withFileTypes: true }).forEach((leafDirent) => {
+                                if (leafDirent.isFile() && leafDirent.name.endsWith('.json')) {
+                                    const topic = `${dirent.name}/${subDirent.name}/${leafDirent.name.replace(/\.json$/, '')}`;
+                                    try {
+                                        const raw = fs.readFileSync(path.join(nestedPath, leafDirent.name), 'utf-8');
+                                        merged[topic] = JSON.parse(raw);
+                                    }
+                                    catch {
+                                        /* ignore parsing errors */
+                                    }
+                                }
+                            });
+                        }
+                        else if (subDirent.isFile() && subDirent.name.endsWith('.json')) {
+                            const topic = `${dirent.name}/${subDirent.name.replace(/\.json$/, '')}`;
+                            try {
+                                const raw = fs.readFileSync(nestedPath, 'utf-8');
+                                merged[topic] = JSON.parse(raw);
+                            }
+                            catch {
+                                /* ignore parsing errors */
+                            }
+                        }
+                    });
+                }
+                else if (dirent.isFile() && dirent.name.endsWith('.json')) {
+                    const topic = dirent.name.replace(/\.json$/, '');
+                    try {
+                        const raw = fs.readFileSync(subpath, 'utf-8');
+                        merged[topic] = JSON.parse(raw);
+                    }
+                    catch {
+                        /* ignore parsing errors */
+                    }
+                }
+            });
+        }
+        catch {
+            // ignore and continue
+        }
+    }
+    return merged;
+}
+const DYNAMIC_FIXTURES = loadDynamicSamples();
+const liquidEngine = new Liquid({
+    cache: false,
+    dynamicPartials: false,
+    strictFilters: false,
+    strictVariables: false,
+});
+// Register Mechanic tags as no-ops for syntax validation
+// Register Mechanic tags in liquidjs (lightweight stubs)
+liquidEngine.registerTag('action', {
+    parse: function (tagToken, remainTokens) {
+        this.tokens = remainTokens;
+        this.args = tagToken.args;
+        this.name = tagToken.name;
+    },
+    render: async function (ctx) {
+        // Do not execute; just mark that we saw an action. Parsing/rendering is handled separately.
+        return '';
+    },
+});
+liquidEngine.registerTag('log', {
+    parse: function (tagToken, remainTokens) {
+        this.tokens = remainTokens;
+        this.args = tagToken.args;
+        this.name = tagToken.name;
+    },
+    render: async function () {
+        return '';
+    },
+});
+liquidEngine.registerTag('error', {
+    parse: function (tagToken, remainTokens) {
+        this.tokens = remainTokens;
+        this.args = tagToken.args;
+        this.name = tagToken.name;
+    },
+    render: async function () {
+        return '';
+    },
+});
+liquidEngine.registerTag('permissions', {
+    parse: function (tagToken, remainTokens) {
+        this.tokens = remainTokens;
+        this.args = tagToken.args;
+        this.name = tagToken.name;
+    },
+    render: async function () {
+        return '';
+    },
+});
+// Register stub filters for Mechanic filters so syntax parsing succeeds
+[...MECHANIC_FILTERS].forEach((filterName) => {
+    liquidEngine.registerFilter(filterName, (v) => v);
+});
+const PREVIEW_WARNINGS = [
+    'Simulator is approximate: Liquid control flow, drops, and Shopify/cache lookups are not fully emulated.',
+    'Actions are captured statically from the template; conditional logic is not executed.',
+];
+function resolveTaskFromStore(handle, store) {
+    const normalized = handle.startsWith('task:') ? handle : `task:${handle}`;
+    const record = store.records.find((r) => r.id === normalized);
+    if (!record || record.kind !== 'task')
+        return undefined;
+    return {
+        id: record.id,
+        name: record.title,
+        tags: record.tags,
+        script: record.script ?? record.content,
+        online_store_javascript: record.online_store_javascript || undefined,
+        order_status_javascript: record.order_status_javascript || undefined,
+        subscriptions: record.events,
+        subscriptions_template: record.subscriptions_template,
+        options: record.options,
+    };
+}
+export function resolveTask(input, store) {
+    if (input.handle) {
+        const resolved = resolveTaskFromStore(input.handle, store);
+        if (resolved)
+            return resolved;
+    }
+    if (input.task) {
+        const parsed = inlineTaskSchema.parse(input.task);
+        return {
+            id: parsed.id,
+            name: parsed.name,
+            tags: parsed.tags,
+            script: parsed.script,
+            online_store_javascript: parsed.online_store_javascript,
+            order_status_javascript: parsed.order_status_javascript,
+            subscriptions: parsed.subscriptions,
+            subscriptions_template: parsed.subscriptions_template,
+            options: parsed.options,
+            preview_event_definitions: parsed.preview_event_definitions,
+        };
+    }
+    throw new Error('No task provided. Supply a handle or a task object.');
+}
+function evaluateExpression(expression, context, warnings) {
+    // Support simple dot/bracket paths and a tiny filter set.
+    const [rawPath, ...filters] = expression.split('|').map((part) => part.trim());
+    const path = rawPath.replace(/\[\"?([^\]]+?)\"?\]/g, '.$1');
+    let value = path.split('.').reduce((acc, key) => (acc && key in acc ? acc[key] : undefined), context);
+    filters.forEach((filter) => {
+        if (filter === 'json') {
+            value = JSON.stringify(value);
+        }
+        else if (filter === 'upcase' && typeof value === 'string') {
+            value = value.toUpperCase();
+        }
+        else if (filter === 'downcase' && typeof value === 'string') {
+            value = value.toLowerCase();
+        }
+        else if (filter.length > 0) {
+            warnings.push(`Unsupported filter "${filter}"`);
+        }
+    });
+    return value === undefined ? '' : value;
+}
+function renderTemplate(template, context, warnings) {
+    return template.replace(/{{\s*([^}]+)\s*}}/g, (_match, expr) => {
+        const value = evaluateExpression(expr, context, warnings);
+        return typeof value === 'string' ? value : JSON.stringify(value);
+    });
+}
+function parseActions(script, context, warnings) {
+    const actions = [];
+    const blockRegex = /{%\s*action\s+"([^"]+)"[^%]*%}([\s\S]*?){%\s*endaction\s*%}/gi;
+    let match;
+    while ((match = blockRegex.exec(script)) !== null) {
+        const [, type, bodyRaw] = match;
+        const rendered = renderTemplate(bodyRaw.trim(), context, warnings);
+        let parsed;
+        try {
+            parsed = JSON.parse(rendered);
+        }
+        catch {
+            parsed = undefined;
+        }
+        actions.push({
+            type,
+            raw: bodyRaw.trim(),
+            rendered,
+            parsed,
+        });
+    }
+    const inlineRegex = /{%\s*action\s+"([^"]+)"\s*,\s*([^%]+)%}/gi;
+    while ((match = inlineRegex.exec(script)) !== null) {
+        const [, type, inlineRaw] = match;
+        const rendered = renderTemplate(inlineRaw.trim(), context, warnings);
+        let parsed;
+        try {
+            parsed = JSON.parse(rendered);
+        }
+        catch {
+            parsed = rendered;
+        }
+        actions.push({
+            type,
+            raw: inlineRaw.trim(),
+            rendered,
+            parsed,
+        });
+    }
+    return actions;
+}
+function parseTagNames(script) {
+    const tags = [];
+    const tagRegex = /{%-?\s*([a-zA-Z_]+)\b[^%]*%}/g;
+    let match;
+    while ((match = tagRegex.exec(script)) !== null) {
+        tags.push(match[1]);
+    }
+    return tags;
+}
+function parseFilterNames(script) {
+    const filters = [];
+    const filterRegex = /\|\s*([a-zA-Z_][a-zA-Z0-9_]*)/g;
+    let match;
+    while ((match = filterRegex.exec(script)) !== null) {
+        filters.push(match[1]);
+    }
+    return filters;
+}
+function parseLogs(script, context, warnings) {
+    const logs = [];
+    const logRegex = /{%\s*log\s+([^%]+)%}/gi;
+    let match;
+    while ((match = logRegex.exec(script)) !== null) {
+        const [, payload] = match;
+        const raw = payload.trim();
+        const rendered = renderTemplate(raw, context, warnings);
+        const evaluated = evaluateExpression(raw, context, warnings);
+        const value = evaluated === ''
+            ? rendered
+            : typeof evaluated === 'string'
+                ? evaluated
+                : JSON.stringify(evaluated);
+        logs.push(value);
+    }
+    return logs;
+}
+function detectTopic(task, topicOverride, payloadTopic) {
+    if (topicOverride?.trim())
+        return topicOverride.trim();
+    if (payloadTopic?.trim())
+        return payloadTopic.trim();
+    if (task.subscriptions && task.subscriptions.length > 0)
+        return task.subscriptions[0];
+    if (task.subscriptions_template) {
+        const lines = task.subscriptions_template
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+        if (lines.length > 0)
+            return lines[0];
+    }
+    return DEFAULT_CUSTOM_TOPIC;
+}
+function resolvePayload(topic, payload) {
+    if (payload)
+        return payload;
+    if (DYNAMIC_FIXTURES[topic])
+        return DYNAMIC_FIXTURES[topic];
+    if (PREVIEW_FIXTURES[topic])
+        return PREVIEW_FIXTURES[topic];
+    return { message: `Preview payload for ${topic}` };
+}
+function normalizeTopic(topicWithOffset) {
+    const offsetIndex = topicWithOffset.indexOf('+');
+    return offsetIndex >= 0 ? topicWithOffset.slice(0, offsetIndex) : topicWithOffset;
+}
+function isLikelyValidTopic(topic) {
+    // Expect domain/subject/verb
+    return /^[a-z0-9_]+\/[a-z0-9_]+\/[a-z0-9_]+$/i.test(topic);
+}
+async function renderLiquid(template, context) {
+    return liquidEngine.parseAndRender(template, context);
+}
+async function renderSubscriptionsTemplate(template, context, errors) {
+    try {
+        const rendered = await renderLiquid(template, context);
+        return rendered
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(`Subscriptions template Liquid error: ${message}`);
+        return [];
+    }
+}
+function validateLiquidSyntax(script, errors, warnings) {
+    try {
+        void liquidEngine.parse(script);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`Liquid syntax warning: ${message}`);
+    }
+}
+export function lintTask(task) {
+    const errors = [];
+    const warnings = [...PREVIEW_WARNINGS];
+    const notes = [];
+    if (!task.script || task.script.trim().length === 0) {
+        errors.push('Task is missing a script.');
+    }
+    if (task.script) {
+        validateLiquidSyntax(task.script, errors, warnings);
+    }
+    if (task.subscriptions_template) {
+        validateLiquidSyntax(task.subscriptions_template, errors, warnings);
+    }
+    if (!task.subscriptions?.length && !task.subscriptions_template) {
+        warnings.push(`No subscriptions provided; preview will default to ${DEFAULT_CUSTOM_TOPIC}.`);
+    }
+    const topicsToCheck = (task.subscriptions || []).map((sub) => normalizeTopic(sub));
+    topicsToCheck.forEach((topic) => {
+        if (!isLikelyValidTopic(topic)) {
+            warnings.push(`Subscription topic "${topic}" is not in domain/subject/verb form (e.g., shopify/orders/create).`);
+        }
+        else if (!topic.startsWith('shopify/') && !topic.startsWith('mechanic/') && !topic.startsWith('user/')) {
+            warnings.push(`Subscription topic "${topic}" uses an uncommon domain; expected shopify/, mechanic/, or user/.`);
+        }
+    });
+    if (task.preview_event_definitions) {
+        task.preview_event_definitions.forEach((definition, index) => {
+            const topic = normalizeTopic(definition.event_attributes?.topic || '');
+            if (topic && !isLikelyValidTopic(topic)) {
+                warnings.push(`Preview event definition #${index + 1} has a topic that is not domain/subject/verb.`);
+            }
+        });
+    }
+    const parsedActions = task.script ? parseActions(task.script, {}, []) : [];
+    parsedActions.forEach((action) => {
+        if (action.type && !ALLOWED_ACTIONS.has(action.type)) {
+            warnings.push(`Action "${action.type}" is not recognized as a standard Mechanic action.`);
+        }
+    });
+    // Check for some risky patterns in preview detection
+    if (task.script?.includes('event.preview == false') || task.script?.includes('event.preview === false')) {
+        warnings.push('Avoid `event.preview == false`; use `event.preview` to detect preview, and `event.preview != true` to detect live.');
+    }
+    if (task.script?.includes('shopify')) {
+        warnings.push('Shopify calls are not executed in the JS simulator; provide stub data if needed.');
+    }
+    if (task.script?.includes('cache')) {
+        warnings.push('Cache lookups are not available in the simulator.');
+    }
+    if (task.script) {
+        const tagNames = parseTagNames(task.script);
+        tagNames.forEach((tag) => {
+            if (!BASE_LIQUID_TAGS.has(tag) && !MECHANIC_TAGS.has(tag)) {
+                warnings.push(`Tag "${tag}" is not in the known Liquid/Mechanic allowlist (may still be valid in full engine).`);
+            }
+        });
+        const filterNames = parseFilterNames(task.script);
+        filterNames.forEach((filter) => {
+            if (!BASE_LIQUID_FILTERS.has(filter) && !MECHANIC_FILTERS.has(filter)) {
+                warnings.push(`Filter "${filter}" is not in the known Liquid/Mechanic allowlist (may still be valid in full engine).`);
+            }
+        });
+    }
+    notes.push('Simulator runs offline with a minimal Liquid subset and static action capture.');
+    return lintTaskOutputSchema.parse({ errors, warnings, notes });
+}
+export function previewTask(task, context) {
+    const warnings = [...PREVIEW_WARNINGS];
+    const errors = [];
+    const notes = [];
+    if (!task.script) {
+        errors.push('No script provided to render.');
+    }
+    const resolvedOptions = task.options || {};
+    const topics = [];
+    if (task.preview_event_definitions && task.preview_event_definitions.length > 0) {
+        task.preview_event_definitions.forEach((definition) => {
+            const topic = definition.event_attributes?.topic;
+            if (topic) {
+                topics.push(topic);
+            }
+        });
+    }
+    else if (task.subscriptions && task.subscriptions.length > 0) {
+        topics.push(...task.subscriptions.map((t) => normalizeTopic(t)));
+    }
+    else if (task.subscriptions_template) {
+        // best effort: include static lines without Liquid; otherwise warn and fall back
+        const staticLines = task.subscriptions_template
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.includes('{') && !line.includes('%'));
+        if (staticLines.length > 0) {
+            topics.push(...staticLines.map((t) => normalizeTopic(t)));
+        }
+        else {
+            warnings.push('subscriptions_template includes Liquid; sandbox did not evaluate it. Defaulting to fallback preview topic.');
+        }
+    }
+    if (topics.length === 0) {
+        topics.push(DEFAULT_CUSTOM_TOPIC);
+    }
+    const events = topics.map((topic, idx) => {
+        const definition = task.preview_event_definitions?.[idx];
+        const data = definition?.event_attributes?.data ||
+            resolvePayload(topic, context.payload?.data);
+        const evt = { topic, data, preview: true };
+        const renderContext = {
+            event: evt,
+            options: resolvedOptions,
+            task: {
+                id: task.id || 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+                name: task.name || '(preview)',
+                tags: task.tags || [],
+            },
+        };
+        const actions = task.script ? parseActions(task.script, renderContext, warnings) : [];
+        const logs = task.script ? parseLogs(task.script, renderContext, warnings) : [];
+        return { event: evt, actions, logs };
+    });
+    if (events.length > 1) {
+        notes.push(`Multiple preview events detected (${events.length}); showing combined actions/logs, first event shown in response.`);
+    }
+    const combinedActions = events.flatMap((e) => e.actions);
+    const combinedLogs = events.flatMap((e) => e.logs);
+    if (combinedActions.length === 0) {
+        warnings.push('No actions detected in script. Conditional logic is not evaluated; ensure actions are guarded by event.preview only if intended.');
+    }
+    // Select first event for schema compatibility; include combined actions/logs
+    const primaryEvent = events[0]?.event || { topic: topics[0], data: {}, preview: true };
+    return previewTaskOutputSchema.parse({
+        event: primaryEvent,
+        actions: combinedActions,
+        logs: combinedLogs,
+        warnings,
+        errors,
+        notes,
+    });
+}

package/dist/tests/task-dev.smoke.js

@@ -0,0 +1,32 @@
+import { strict as assert } from 'node:assert';
+import { lintTask, previewTask, resolveTask } from '../task-dev.js';
+async function run() {
+    const inlineTask = {
+        name: 'Preview smoke',
+        subscriptions: ['user/test'],
+        script: '{% action "echo" %}{{ options.message | json }}{% endaction %}',
+        options: { message: 'hi there' },
+    };
+    const resolved = resolveTask({ task: inlineTask }, { records: [] });
+    const lint = lintTask(resolved);
+    assert.equal(lint.errors.length, 0, 'Lint should not surface errors');
+    assert(lint.warnings.length >= 1, 'Lint should surface simulator warnings');
+    const preview = previewTask(resolved, { topic: 'user/test', payload: { data: { foo: 'bar' } } });
+    assert.equal(preview.event.topic, 'user/test', 'Preview should use provided topic');
+    assert.equal(preview.event.data.foo, 'bar', 'Preview should include provided payload data');
+    assert(preview.actions.length === 1, 'Preview should capture one action');
+    assert(preview.actions[0].rendered.includes('hi there'), 'Rendered action should include option value');
+    assert.equal(preview.errors.length, 0, 'Preview should not surface errors');
+    const fixturePreview = previewTask(resolveTask({
+        task: {
+            subscriptions: ['user/event/preview'],
+            script: '{% log event.data.message %}',
+        },
+    }, { records: [] }), {});
+    assert(fixturePreview.logs.some((log) => log.includes('Hello from a preview event')), 'Fixture should populate preview data');
+}
+run().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightward/mechanic-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Mechanic MCP server for docs and task library search",
   "type": "module",
   "main": "dist/index.js",