mcp-mat 0.1.0

package/dist/src/logging.js

@@ -0,0 +1,76 @@
+// Copyright 2025 Penghui Li
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export function createRequestContext(tool, heapPath, privacyMode) {
+    const requestId = crypto.randomUUID();
+    const heapPathDisplay = heapPath
+        ? privacyMode
+            ? `sha256:${crypto.createHash("sha256").update(heapPath).digest("hex")}`
+            : heapPath
+        : undefined;
+    return {
+        requestId,
+        tool,
+        heapPathDisplay,
+        startedAtMs: Date.now(),
+    };
+}
+export function logRequestStart(context) {
+    process.stderr.write(`${JSON.stringify({
+        event: "request_start",
+        request_id: context.requestId,
+        tool: context.tool,
+        heap: context.heapPathDisplay,
+        ts: new Date().toISOString(),
+    })}\n`);
+}
+export function logRequestEnd(context, params) {
+    process.stderr.write(`${JSON.stringify({
+        event: "request_end",
+        request_id: context.requestId,
+        tool: context.tool,
+        heap: context.heapPathDisplay,
+        status: params.status,
+        category: params.category,
+        exit_code: params.exitCode ?? null,
+        elapsed_ms: params.elapsedMs,
+        artifacts: params.artifacts ?? [],
+        ts: new Date().toISOString(),
+    })}\n`);
+}
+export function persistDebugLog(params) {
+    if (!params.enabled) {
+        return;
+    }
+    fs.mkdirSync(params.logDir, { recursive: true });
+    const logPath = path.join(params.logDir, `${params.context.requestId}.log`);
+    const payload = {
+        request_id: params.context.requestId,
+        tool: params.context.tool,
+        heap: params.context.heapPathDisplay,
+        started_at: new Date(params.context.startedAtMs).toISOString(),
+        duration_ms: params.run.durationMs,
+        exit_code: params.run.exitCode,
+        signal: params.run.signal,
+        timed_out: params.run.timedOut,
+        command: params.privacyMode ? "[redacted]" : params.run.command,
+        args: params.privacyMode ? ["[redacted]"] : params.run.args,
+        stdout: params.run.stdout,
+        stderr: params.run.stderr,
+    };
+    fs.writeFileSync(logPath, JSON.stringify(payload, null, 2));
+}
+//# sourceMappingURL=logging.js.map

package/dist/src/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/logging.ts"],"names":[],"mappings":"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"}

package/dist/src/mat/artifacts.d.ts

@@ -0,0 +1,20 @@
+export interface QueryArtifacts {
+    queryDir: string | null;
+    queryZip: string | null;
+    resultTxt: string | null;
+    generatedFiles: string[];
+}
+export interface ReportArtifacts {
+    reportDir: string | null;
+    reportZip: string | null;
+    generatedFiles: string[];
+}
+export interface IndexArtifacts {
+    indexPresent: boolean;
+    indexFiles: string[];
+    threadsFile: string | null;
+    lastModified: string | null;
+}
+export declare function resolveQueryArtifacts(heapPath: string, startedAtMs?: number): QueryArtifacts;
+export declare function resolveReportArtifacts(heapPath: string, startedAtMs?: number): ReportArtifacts;
+export declare function resolveIndexArtifacts(heapPath: string): IndexArtifacts;

package/dist/src/mat/artifacts.js

@@ -0,0 +1,200 @@
+// Copyright 2025 Penghui Li
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import fs from "node:fs";
+import path from "node:path";
+function heapBases(heapPath) {
+    const base = path.basename(heapPath);
+    const stem = path.parse(heapPath).name;
+    return [...new Set([base, stem])];
+}
+function safeReadDir(directory) {
+    try {
+        return fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function latestByMtime(paths) {
+    if (paths.length === 0)
+        return null;
+    const entries = paths
+        .map((p) => {
+        try {
+            return { p, mtime: fs.statSync(p).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((entry) => entry !== null);
+    if (entries.length === 0)
+        return null;
+    return entries.sort((a, b) => b.mtime - a.mtime)[0].p;
+}
+function isRecentEnough(fullPath, startedAtMs) {
+    if (startedAtMs === undefined)
+        return true;
+    try {
+        return fs.statSync(fullPath).mtimeMs >= startedAtMs - 2000;
+    }
+    catch {
+        return false;
+    }
+}
+function discoverGeneratedNearHeap(heapPath, startedAtMs) {
+    const parent = path.dirname(heapPath);
+    const bases = heapBases(heapPath);
+    const entries = safeReadDir(parent);
+    return entries
+        .filter((entry) => {
+        const matchesBase = bases.some((base) => entry.name.startsWith(base));
+        if (!matchesBase) {
+            return false;
+        }
+        if (entry.name === path.basename(heapPath)) {
+            return false;
+        }
+        const fullPath = path.join(parent, entry.name);
+        return isRecentEnough(fullPath, startedAtMs);
+    })
+        .map((entry) => path.join(parent, entry.name))
+        .sort();
+}
+function findQueryCommandText(queryDir, startedAtMs) {
+    const pagesDir = path.join(queryDir, "pages");
+    if (!fs.existsSync(pagesDir) || !fs.statSync(pagesDir).isDirectory()) {
+        return null;
+    }
+    const candidates = safeReadDir(pagesDir)
+        .filter((entry) => entry.isFile() && /^Query_Command[_\d]*\d+\.txt$/.test(entry.name))
+        .map((entry) => path.join(pagesDir, entry.name))
+        .filter((fullPath) => isRecentEnough(fullPath, startedAtMs));
+    return latestByMtime(candidates);
+}
+export function resolveQueryArtifacts(heapPath, startedAtMs) {
+    const parent = path.dirname(heapPath);
+    const bases = heapBases(heapPath);
+    const queryDirCandidates = [];
+    const queryZipCandidates = [];
+    // Directories whose own mtime is stale but may contain recently-updated files
+    const staleDirCandidates = [];
+    for (const entry of safeReadDir(parent)) {
+        const fullPath = path.join(parent, entry.name);
+        const isMatchingQuery = bases.some((base) => entry.name === `${base}_Query` || entry.name.startsWith(`${base}_Query`));
+        if (!isMatchingQuery) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            if (isRecentEnough(fullPath, startedAtMs)) {
+                queryDirCandidates.push(fullPath);
+            }
+            else {
+                staleDirCandidates.push(fullPath);
+            }
+        }
+        if (entry.isFile() && entry.name.endsWith(".zip")) {
+            if (isRecentEnough(fullPath, startedAtMs)) {
+                queryZipCandidates.push(fullPath);
+            }
+        }
+    }
+    const queryDir = latestByMtime(queryDirCandidates);
+    const queryZip = latestByMtime(queryZipCandidates);
+    // Look for result txt in a recent directory first, then fall back to stale
+    // directories whose individual files may have been updated (overwriting an
+    // existing file does not bump the parent directory mtime on macOS/Linux).
+    let resultTxt = queryDir ? findQueryCommandText(queryDir, startedAtMs) : null;
+    if (!resultTxt) {
+        for (const staleDir of staleDirCandidates) {
+            resultTxt = findQueryCommandText(staleDir, startedAtMs);
+            if (resultTxt)
+                break;
+        }
+    }
+    const generated = discoverGeneratedNearHeap(heapPath, startedAtMs);
+    if (resultTxt && !generated.includes(resultTxt)) {
+        generated.push(resultTxt);
+        generated.sort();
+    }
+    return {
+        queryDir: queryDir ?? (resultTxt ? path.dirname(path.dirname(resultTxt)) : null),
+        queryZip,
+        resultTxt,
+        generatedFiles: generated,
+    };
+}
+export function resolveReportArtifacts(heapPath, startedAtMs) {
+    const generated = discoverGeneratedNearHeap(heapPath, startedAtMs);
+    const dirs = generated.filter((item) => {
+        try {
+            return fs.statSync(item).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    const zips = generated.filter((item) => item.endsWith(".zip"));
+    return {
+        reportDir: latestByMtime(dirs),
+        reportZip: latestByMtime(zips),
+        generatedFiles: generated,
+    };
+}
+export function resolveIndexArtifacts(heapPath) {
+    const parent = path.dirname(heapPath);
+    // MAT names index files using the heap stem (without extension):
+    //   heap.hprof -> heap.index, heap.idx.index, heap.threads, etc.
+    const heapStem = path.parse(heapPath).name;
+    const indexFiles = [];
+    let threadsFile = null;
+    let lastModifiedMs = 0;
+    for (const entry of safeReadDir(parent)) {
+        if (!entry.isFile()) {
+            continue;
+        }
+        const fullPath = path.join(parent, entry.name);
+        if (!entry.name.startsWith(heapStem)) {
+            continue;
+        }
+        const isIndex = entry.name.includes(".index");
+        const isThreads = entry.name.endsWith(".threads") || entry.name.includes("threads");
+        if (!isIndex && !isThreads) {
+            continue;
+        }
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(fullPath).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (mtimeMs > lastModifiedMs) {
+            lastModifiedMs = mtimeMs;
+        }
+        if (isIndex) {
+            indexFiles.push(fullPath);
+        }
+        if (isThreads && threadsFile === null) {
+            threadsFile = fullPath;
+        }
+    }
+    return {
+        indexPresent: indexFiles.length > 0,
+        indexFiles: indexFiles.sort(),
+        threadsFile,
+        lastModified: lastModifiedMs > 0 ? new Date(lastModifiedMs).toISOString() : null,
+    };
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/src/mat/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../src/mat/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/src/mat/commandBuilder.d.ts

@@ -0,0 +1,25 @@
+import type { RunCommand } from "../types.js";
+export interface BaseMatCommandArgs {
+    javaPath: string;
+    launcherPath: string;
+    heapPath: string;
+    configDir: string;
+    dataDir: string;
+    xmxMb: number;
+    timeoutSec: number;
+}
+export declare function formatOqlForMatCommand(oql: string): string;
+export declare function buildParseReportCommand(base: BaseMatCommandArgs, reportId: string, options?: Record<string, string | number | boolean>): RunCommand;
+export declare function buildOqlCommand(base: BaseMatCommandArgs, params: {
+    oql: string;
+    format: "txt" | "html" | "csv";
+    unzip: boolean;
+    limit?: number;
+}): RunCommand;
+export declare function buildGenericCommand(base: BaseMatCommandArgs, params: {
+    commandName: string;
+    commandArgs?: string;
+    format: "txt" | "html" | "csv";
+    unzip: boolean;
+    limit?: number;
+}): RunCommand;

package/dist/src/mat/commandBuilder.js

@@ -0,0 +1,90 @@
+// Copyright 2025 Penghui Li
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+const ASM_EXPORT = "--add-exports=java.base/jdk.internal.org.objectweb.asm=ALL-UNNAMED";
+const PARSE_APP_ID = "org.eclipse.mat.api.parse";
+function buildCommonArgs(base) {
+    return [
+        `-Xmx${base.xmxMb}m`,
+        ASM_EXPORT,
+        "-jar",
+        base.launcherPath,
+        "-consolelog",
+        "-nosplash",
+        "-configuration",
+        base.configDir,
+        "-data",
+        base.dataDir,
+        "-application",
+        PARSE_APP_ID,
+        base.heapPath,
+    ];
+}
+function optionToArg(key, value) {
+    if (typeof value === "boolean") {
+        return value ? `-${key}` : `-${key}=false`;
+    }
+    if (typeof value === "number") {
+        return `-${key}=${value}`;
+    }
+    if (value.trim().length === 0) {
+        return null;
+    }
+    return `-${key}=${value}`;
+}
+export function formatOqlForMatCommand(oql) {
+    const escaped = oql.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+    return `"${escaped}"`;
+}
+export function buildParseReportCommand(base, reportId, options) {
+    const args = buildCommonArgs(base);
+    for (const [key, value] of Object.entries(options ?? {})) {
+        const arg = optionToArg(key, value);
+        if (arg) {
+            args.push(arg);
+        }
+    }
+    args.push(reportId);
+    return {
+        command: base.javaPath,
+        args,
+        timeoutSec: base.timeoutSec,
+    };
+}
+function buildQueryStyleCommand(base, commandStr, params) {
+    const args = buildCommonArgs(base);
+    args.push(`-command=${commandStr}`);
+    args.push(`-format=${params.format}`);
+    if (params.unzip) {
+        args.push("-unzip");
+    }
+    if (params.limit !== undefined) {
+        args.push(`-limit=${params.limit}`);
+    }
+    args.push("org.eclipse.mat.api:query");
+    return {
+        command: base.javaPath,
+        args,
+        timeoutSec: base.timeoutSec,
+    };
+}
+export function buildOqlCommand(base, params) {
+    return buildQueryStyleCommand(base, `oql ${formatOqlForMatCommand(params.oql)}`, params);
+}
+export function buildGenericCommand(base, params) {
+    const commandStr = params.commandArgs
+        ? `${params.commandName} ${params.commandArgs}`
+        : params.commandName;
+    return buildQueryStyleCommand(base, commandStr, params);
+}
+//# sourceMappingURL=commandBuilder.js.map

package/dist/src/mat/commandBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandBuilder.js","sourceRoot":"","sources":["../../../src/mat/commandBuilder.ts"],"names":[],"mappings":"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"}

package/dist/src/mat/errorClassifier.d.ts

@@ -0,0 +1,3 @@
+import { MatMcpError, type RunResult } from "../types.js";
+export declare function classifyRunFailure(run: RunResult, tailChars: number, timeoutSec?: number): MatMcpError;
+export declare function classifySpawnError(error: unknown): MatMcpError;

package/dist/src/mat/errorClassifier.js

@@ -0,0 +1,98 @@
+// Copyright 2025 Penghui Li
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { tail } from "./runner.js";
+import { MatMcpError } from "../types.js";
+const WRITE_PERMISSION_PATTERNS = [
+    /permission denied/i,
+    /access is denied/i,
+    /read-only file system/i,
+    /cannot create/i,
+    /failed to create/i,
+    /lock\.index/i,
+];
+const INVALID_QUERY_PATTERNS = [
+    /syntax/i,
+    /parse error/i,
+    /unexpected token/i,
+    /invalid query/i,
+    /query command/i,
+];
+function includesPattern(text, patterns) {
+    return patterns.some((pattern) => pattern.test(text));
+}
+export function classifyRunFailure(run, tailChars, timeoutSec) {
+    const stdoutTail = tail(run.stdout, tailChars);
+    const stderrTail = tail(run.stderr, tailChars);
+    const merged = `${stdoutTail}\n${stderrTail}`;
+    if (run.timedOut) {
+        const durationStr = `${Math.round(run.durationMs / 1000)}s`;
+        const limitStr = timeoutSec !== undefined ? `, limit ${timeoutSec}s` : "";
+        return new MatMcpError({
+            category: "MAT_TIMEOUT",
+            message: `MAT process exceeded timeout (ran ${durationStr}${limitStr}).`,
+            hint: "Increase timeout_sec or run a smaller report/query.",
+            stdoutTail,
+            stderrTail,
+            exitCode: run.exitCode,
+        });
+    }
+    if (includesPattern(merged, WRITE_PERMISSION_PATTERNS)) {
+        return new MatMcpError({
+            category: "WRITE_PERMISSION_DENIED",
+            message: "MAT could not write lock/index/report artifacts near the heap dump.",
+            hint: "Grant write permission on the heap directory or analyze a copy in writable storage.",
+            stdoutTail,
+            stderrTail,
+            exitCode: run.exitCode,
+        });
+    }
+    const likelyInvalidQuery = includesPattern(merged, INVALID_QUERY_PATTERNS) && /oql/i.test(merged);
+    if (likelyInvalidQuery) {
+        return new MatMcpError({
+            category: "INVALID_QUERY",
+            message: "MAT rejected the OQL query.",
+            hint: "Validate OQL syntax and use mat_oql_spec for parser-mode-safe query patterns.",
+            stdoutTail,
+            stderrTail,
+            exitCode: run.exitCode,
+        });
+    }
+    return new MatMcpError({
+        category: "MAT_PARSE_FAILED",
+        message: "MAT exited with a non-zero status.",
+        hint: "Inspect stderr_tail for MAT diagnostics.",
+        stdoutTail,
+        stderrTail,
+        exitCode: run.exitCode,
+    });
+}
+export function classifySpawnError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof Error ? error.code : undefined;
+    if (code === "EACCES") {
+        return new MatMcpError({
+            category: "MAT_NOT_FOUND",
+            message: `Permission denied launching MAT process: ${message}`,
+            hint: "Ensure JAVA_PATH points to an executable file with proper permissions.",
+        });
+    }
+    return new MatMcpError({
+        category: "MAT_NOT_FOUND",
+        message: `Failed to launch MAT process: ${message}`,
+        hint: code === "ENOENT"
+            ? "Java binary not found. Install Java or set JAVA_PATH to a valid java executable."
+            : "Verify JAVA_PATH and MAT_LAUNCHER are valid and executable.",
+    });
+}
+//# sourceMappingURL=errorClassifier.js.map

package/dist/src/mat/errorClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorClassifier.js","sourceRoot":"","sources":["../../../src/mat/errorClassifier.ts"],"names":[],"mappings":"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"}

package/dist/src/mat/launcher.d.ts

@@ -0,0 +1,6 @@
+export interface LauncherOptions {
+    matLauncher?: string;
+    matHome?: string;
+}
+export declare function resolveMatLauncher(options: LauncherOptions): string;
+export declare function detectJavaVersion(javaPath: string): string;

package/dist/src/mat/launcher.js

@@ -0,0 +1,89 @@
+// Copyright 2025 Penghui Li
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { MatMcpError } from "../types.js";
+export function resolveMatLauncher(options) {
+    if (options.matLauncher) {
+        const absolute = path.resolve(options.matLauncher);
+        try {
+            return fs.realpathSync(absolute);
+        }
+        catch {
+            throw new MatMcpError({
+                category: "MAT_NOT_FOUND",
+                message: `MAT launcher not found: ${absolute}`,
+                hint: "Set MAT_LAUNCHER to a valid org.eclipse.equinox.launcher_*.jar path.",
+            });
+        }
+    }
+    if (!options.matHome) {
+        throw new MatMcpError({
+            category: "MAT_NOT_FOUND",
+            message: "MAT launcher is not configured.",
+            hint: "Set MAT_LAUNCHER or MAT_HOME before starting the server.",
+        });
+    }
+    const pluginDir = path.join(path.resolve(options.matHome), "plugins");
+    if (!fs.existsSync(pluginDir) || !fs.statSync(pluginDir).isDirectory()) {
+        throw new MatMcpError({
+            category: "MAT_NOT_FOUND",
+            message: `MAT plugins directory missing: ${pluginDir}`,
+            hint: "Verify MAT_HOME points to the Eclipse MAT installation root.",
+        });
+    }
+    const launcherCandidate = fs
+        .readdirSync(pluginDir)
+        .filter((name) => /^org\.eclipse\.equinox\.launcher_.*\.jar$/.test(name))
+        .sort()
+        .at(-1);
+    if (!launcherCandidate) {
+        throw new MatMcpError({
+            category: "MAT_NOT_FOUND",
+            message: `No launcher jar found in: ${pluginDir}`,
+            hint: "Install Eclipse MAT or configure MAT_LAUNCHER explicitly.",
+        });
+    }
+    return path.join(pluginDir, launcherCandidate);
+}
+export function detectJavaVersion(javaPath) {
+    const result = spawnSync(javaPath, ["-version"], {
+        encoding: "utf8",
+        timeout: 10_000,
+    });
+    if (result.error) {
+        throw new MatMcpError({
+            category: "MAT_NOT_FOUND",
+            message: `Failed to run Java: ${result.error.message}`,
+            hint: "Set JAVA_PATH to a valid java executable.",
+        });
+    }
+    if (result.status !== 0) {
+        throw new MatMcpError({
+            category: "MAT_NOT_FOUND",
+            message: "Java runtime is unavailable.",
+            hint: "Install Java and ensure JAVA_PATH points to the java binary.",
+            stdoutTail: result.stdout ?? "",
+            stderrTail: result.stderr ?? "",
+            exitCode: result.status,
+        });
+    }
+    const versionLine = `${result.stderr ?? ""}\n${result.stdout ?? ""}`
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    return versionLine ?? "unknown";
+}
+//# sourceMappingURL=launcher.js.map

package/dist/src/mat/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../../src/mat/launcher.ts"],"names":[],"mappings":"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"}

package/dist/src/mat/oqlSpec.d.ts

@@ -0,0 +1,3 @@
+import { type MatOqlSpecSuccess } from "../types.js";
+export declare const MAT_OQL_SPEC: Omit<MatOqlSpecSuccess, "status">;
+export declare function normalizeOqlInput(oql: string): string;