@thotischner/observability-mcp 1.3.4 → 1.4.1

package/dist/cli/lib.test.js

@@ -0,0 +1,134 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseArgs, pickFreePort, composeOverride, resolveCatalogSource, formatPluginList, formatPluginInfo, DEFAULT_CATALOG_URL, } from "./lib.js";
+const CAT = {
+    catalogVersion: 1,
+    connectors: [
+        {
+            name: "prometheus",
+            displayName: "Prometheus",
+            description: "PromQL metrics.",
+            tier: "official",
+            builtin: true,
+            signalTypes: ["metrics"],
+            latest: "1.4.0",
+            versions: [{ version: "1.4.0", releasedAt: "2026-05-15", serverCompat: ">=1.4.0" }],
+        },
+        {
+            name: "tempo",
+            displayName: "Grafana Tempo",
+            description: "TraceQL.",
+            tier: "third-party",
+            signalTypes: ["traces"],
+            versions: [
+                { version: "1.0.0", releasedAt: "2026-05-15", integrity: "sha256-AAAA=", signatureUrl: "https://x/s.sig" },
+            ],
+        },
+    ],
+};
+test("parseArgs: command, sub, positionals", () => {
+    const p = parseArgs(["demo", "up", "extra"]);
+    assert.equal(p.command, "demo");
+    assert.equal(p.sub, "up");
+    assert.deepEqual(p.positionals, ["extra"]);
+});
+test("parseArgs: --flag=val, --flag val, boolean, -f val", () => {
+    const p = parseArgs(["plugin", "install", "loki", "--from=/m", "--ver", "1.2.0", "--json", "-f", "x"]);
+    assert.equal(p.command, "plugin");
+    assert.equal(p.sub, "install");
+    assert.deepEqual(p.positionals, ["loki"]);
+    assert.equal(p.flags.from, "/m");
+    assert.equal(p.flags.ver, "1.2.0");
+    assert.equal(p.flags.json, true);
+    assert.equal(p.flags.f, "x");
+});
+test("parseArgs: empty argv", () => {
+    const p = parseArgs([]);
+    assert.equal(p.command, "");
+    assert.equal(p.sub, undefined);
+});
+test("pickFreePort returns desired when free", () => {
+    assert.equal(pickFreePort(3000, () => false), 3000);
+});
+test("pickFreePort skips used ports", () => {
+    const used = new Set([3000, 3001, 3002]);
+    assert.equal(pickFreePort(3000, (p) => used.has(p)), 3003);
+});
+test("pickFreePort throws when span exhausted", () => {
+    assert.throws(() => pickFreePort(3000, () => true, 5), /no free port/);
+});
+test("composeOverride emits !override port mappings", () => {
+    const y = composeOverride([
+        { service: "mcp-server", host: 3001, container: 3000 },
+        { service: "loki", host: 3101, container: 3100 },
+    ]);
+    assert.match(y, /^services:\n/);
+    assert.match(y, /  mcp-server:\n    ports: !override\n      - "3001:3000"/);
+    assert.match(y, /  loki:\n    ports: !override\n      - "3101:3100"/);
+});
+test("resolveCatalogSource: explicit url, explicit path, local, default", () => {
+    assert.deepEqual(resolveCatalogSource("https://h/x.json", null), { kind: "url", location: "https://h/x.json" });
+    assert.deepEqual(resolveCatalogSource("/tmp/c.json", null), { kind: "file", location: "/tmp/c.json" });
+    assert.deepEqual(resolveCatalogSource(undefined, "/repo/hub/catalog/index.json"), { kind: "file", location: "/repo/hub/catalog/index.json" });
+    assert.deepEqual(resolveCatalogSource(undefined, null), { kind: "url", location: DEFAULT_CATALOG_URL });
+});
+test("formatPluginList: header, sorted rows, builtin+tier flags", () => {
+    const out = formatPluginList(CAT);
+    const lines = out.split("\n");
+    assert.match(lines[0], /^NAME\s+LATEST\s+SIGNALS\s+TIER$/);
+    // sorted: prometheus before tempo
+    assert.ok(lines[1].startsWith("prometheus"));
+    assert.match(lines[1], /builtin,official/);
+    assert.ok(lines[2].startsWith("tempo"));
+    assert.match(lines[2], /third-party/);
+});
+test("formatPluginInfo: versions + integrity/signature surfaced", () => {
+    const info = formatPluginInfo(CAT.connectors[1]);
+    assert.match(info, /Grafana Tempo {2}\(tempo\)/);
+    assert.match(info, /tier: {6}third-party/);
+    assert.match(info, /1\.0\.0 \(2026-05-15\)/);
+    assert.match(info, /integrity: sha256-AAAA=/);
+    assert.match(info, /signature: https:\/\/x\/s\.sig/);
+});
+import { parsePluginRef, resolveInstall } from "./lib.js";
+test("parsePluginRef: name and name@version, rejects junk", () => {
+    assert.deepEqual(parsePluginRef("tempo"), { name: "tempo", version: undefined });
+    assert.deepEqual(parsePluginRef("tempo@1.2.3"), { name: "tempo", version: "1.2.3" });
+    assert.deepEqual(parsePluginRef("x@1.0.0-rc.1"), { name: "x", version: "1.0.0-rc.1" });
+    assert.throws(() => parsePluginRef("Bad Name"), /invalid plugin ref/);
+    assert.throws(() => parsePluginRef("tempo@v1"), /invalid plugin ref/);
+});
+test("resolveInstall: builtin short-circuits", () => {
+    const r = resolveInstall(CAT, "prometheus");
+    assert.equal(r.builtin, true);
+    assert.equal(r.name, "prometheus");
+});
+test("resolveInstall: picks latest then specific version", () => {
+    const def = resolveInstall(CAT, "tempo");
+    assert.equal(def.version, "1.0.0");
+    assert.equal(def.builtin, false);
+    assert.equal(def.integrity, "sha256-AAAA=");
+    const pinned = resolveInstall(CAT, "tempo@1.0.0");
+    assert.equal(pinned.version, "1.0.0");
+    assert.throws(() => resolveInstall(CAT, "tempo@9.9.9"), /not found/);
+    assert.throws(() => resolveInstall(CAT, "ghost"), /no connector/);
+});
+import { splitPassthrough, helmReleaseArgs, HELM_CHART } from "./lib.js";
+test("splitPassthrough: splits at first -- ", () => {
+    assert.deepEqual(splitPassthrough(["helm", "install", "obs"]), {
+        argv: ["helm", "install", "obs"],
+        passthrough: [],
+    });
+    assert.deepEqual(splitPassthrough(["helm", "upgrade", "obs", "--", "-n", "mon", "--set", "a=b"]), { argv: ["helm", "upgrade", "obs"], passthrough: ["-n", "mon", "--set", "a=b"] });
+});
+test("helmReleaseArgs: install vs upgrade --install, passthrough appended", () => {
+    assert.deepEqual(helmReleaseArgs("install", "obs", []), ["install", "obs", HELM_CHART]);
+    assert.deepEqual(helmReleaseArgs("upgrade", "obs", ["-n", "mon"]), [
+        "upgrade",
+        "--install",
+        "obs",
+        HELM_CHART,
+        "-n",
+        "mon",
+    ]);
+});

package/dist/config/loader.test.js

@@ -1,15 +1,15 @@
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { writeFileSync, mkdtempSync, rmSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { substituteEnv } from "./loader.js";
 // We test the helper functions by importing the module fresh with different env vars.
 // Since the config path is resolved at import time, we use dynamic imports.
-const TMP_DIR = join(tmpdir(), "observability-mcp-test-" + Date.now());
+let TMP_DIR;
 describe("config/loader", () => {
     beforeEach(() => {
-        mkdirSync(TMP_DIR, { recursive: true });
+        TMP_DIR = mkdtempSync(join(tmpdir(), "observability-mcp-test-"));
     });
     afterEach(() => {
         rmSync(TMP_DIR, { recursive: true, force: true });

package/dist/connectors/hub.d.ts

@@ -0,0 +1,48 @@
+import type { LoadedConnector } from "./loader.js";
+export declare const DEFAULT_HUB_CATALOG_URL = "https://thotischner.github.io/observability-mcp/hub/index.json";
+/** Catalog source: env override wins (airgapped mirror / private hub). */
+export declare function resolveHubCatalogUrl(env?: NodeJS.ProcessEnv): string;
+export interface InstalledConnector {
+    name: string;
+    source: "builtin" | "filesystem" | "config";
+    displayName: string;
+    description: string;
+    version: string | null;
+    signalTypes: string[];
+    capabilities: Record<string, boolean>;
+}
+/** Shape the loader's entries into the UI's installed list. */
+export declare function describeInstalled(loaded: LoadedConnector[]): InstalledConnector[];
+export interface CatalogConnector {
+    name: string;
+    displayName: string;
+    description: string;
+    tier: string;
+    builtin?: boolean;
+    signalTypes: string[];
+    latest?: string;
+    versions: Array<{
+        version: string;
+        tarballUrl?: string;
+        integrity?: string;
+        serverCompat?: string;
+        changelog?: string;
+        releasedAt?: string;
+    }>;
+}
+export interface HubCatalogEntry extends CatalogConnector {
+    installed: boolean;
+    installedVersion: string | null;
+}
+/**
+ * Merge the hub catalog with what's installed so the UI can show
+ * status + offer not-yet-installed connectors.
+ */
+export declare function mergeCatalog(catalog: {
+    connectors?: CatalogConnector[];
+} | null, installed: InstalledConnector[]): HubCatalogEntry[];
+/** Fetch + parse the catalog. fetchImpl injected for tests. */
+export declare function fetchHubCatalog(url: string, fetchImpl?: typeof fetch): Promise<{
+    connectors: CatalogConnector[];
+    catalogVersion?: number;
+}>;

package/dist/connectors/hub.js

@@ -0,0 +1,51 @@
+// Connector-hub integration helpers (pure, IO-injectable so they unit
+// test without network). Powers the Web UI "Connectors" page:
+//   - what's installed/loaded right now
+//   - what the hub catalog offers, with an "installed" marker
+export const DEFAULT_HUB_CATALOG_URL = "https://thotischner.github.io/observability-mcp/hub/index.json";
+/** Catalog source: env override wins (airgapped mirror / private hub). */
+export function resolveHubCatalogUrl(env = process.env) {
+    return env.HUB_CATALOG_URL || DEFAULT_HUB_CATALOG_URL;
+}
+/** Shape the loader's entries into the UI's installed list. */
+export function describeInstalled(loaded) {
+    return loaded
+        .map((p) => ({
+        name: p.name,
+        source: p.source,
+        displayName: p.manifest?.displayName ?? p.name,
+        description: p.manifest?.description ?? "",
+        version: p.manifest?.version ?? null,
+        signalTypes: p.manifest?.signalTypes ?? [],
+        capabilities: p.manifest?.capabilities ?? {},
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Merge the hub catalog with what's installed so the UI can show
+ * status + offer not-yet-installed connectors.
+ */
+export function mergeCatalog(catalog, installed) {
+    const byName = new Map(installed.map((i) => [i.name, i]));
+    return (catalog?.connectors ?? [])
+        .map((c) => {
+        const have = byName.get(c.name);
+        return {
+            ...c,
+            installed: !!have,
+            installedVersion: have?.version ?? null,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Fetch + parse the catalog. fetchImpl injected for tests. */
+export async function fetchHubCatalog(url, fetchImpl = fetch) {
+    const res = await fetchImpl(url);
+    if (!res.ok)
+        throw new Error(`hub catalog HTTP ${res.status} from ${url}`);
+    const body = (await res.json());
+    if (!body || !Array.isArray(body.connectors)) {
+        throw new Error("hub catalog malformed (no connectors[])");
+    }
+    return { connectors: body.connectors, catalogVersion: body.catalogVersion };
+}

package/dist/connectors/hub.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/connectors/hub.test.js

@@ -0,0 +1,52 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveHubCatalogUrl, describeInstalled, mergeCatalog, fetchHubCatalog, DEFAULT_HUB_CATALOG_URL, } from "./hub.js";
+test("resolveHubCatalogUrl: default + env override", () => {
+    assert.equal(resolveHubCatalogUrl({}), DEFAULT_HUB_CATALOG_URL);
+    assert.equal(resolveHubCatalogUrl({ HUB_CATALOG_URL: "http://mirror/idx.json" }), "http://mirror/idx.json");
+});
+test("describeInstalled maps loader entries, sorts, defaults", () => {
+    const loaded = [
+        { name: "loki", source: "builtin", factory: () => ({}) },
+        {
+            name: "datadog",
+            source: "filesystem",
+            factory: () => ({}),
+            manifest: {
+                displayName: "Datadog",
+                description: "DD",
+                version: "1.0.0",
+                signalTypes: ["metrics", "logs"],
+                capabilities: { queryMetrics: true },
+            },
+        },
+    ];
+    const d = describeInstalled(loaded);
+    assert.deepEqual(d.map((x) => x.name), ["datadog", "loki"]); // sorted
+    assert.equal(d[0].displayName, "Datadog");
+    assert.deepEqual(d[0].signalTypes, ["metrics", "logs"]);
+    assert.equal(d[1].displayName, "loki"); // falls back to name
+    assert.equal(d[1].version, null);
+    assert.deepEqual(d[1].capabilities, {});
+});
+test("mergeCatalog marks installed + version, sorts, tolerates null", () => {
+    const installed = describeInstalled([
+        { name: "datadog", source: "filesystem", factory: () => ({}), manifest: { version: "1.0.0" } },
+    ]);
+    const merged = mergeCatalog({ connectors: [
+            { name: "grafana", displayName: "Grafana", description: "", tier: "official", signalTypes: ["metrics"], versions: [{ version: "1.0.0" }] },
+            { name: "datadog", displayName: "Datadog", description: "", tier: "official", signalTypes: ["metrics"], versions: [{ version: "1.0.0" }] },
+        ] }, installed);
+    assert.deepEqual(merged.map((m) => m.name), ["datadog", "grafana"]);
+    assert.equal(merged[0].installed, true);
+    assert.equal(merged[0].installedVersion, "1.0.0");
+    assert.equal(merged[1].installed, false);
+    assert.deepEqual(mergeCatalog(null, installed), []);
+});
+test("fetchHubCatalog: ok, http error, malformed", async () => {
+    const ok = async () => ({ ok: true, status: 200, json: async () => ({ connectors: [{ name: "x" }], catalogVersion: 1 }) });
+    const r = await fetchHubCatalog("u", ok);
+    assert.equal(r.connectors.length, 1);
+    await assert.rejects(() => fetchHubCatalog("u", (async () => ({ ok: false, status: 503, json: async () => ({}) }))), /HTTP 503/);
+    await assert.rejects(() => fetchHubCatalog("u", (async () => ({ ok: true, status: 200, json: async () => ({}) }))), /malformed/);
+});

package/dist/connectors/install.d.ts

@@ -0,0 +1,24 @@
+/** A connector name is safe iff kebab-case ASCII (also blocks traversal). */
+export declare function isValidConnectorName(name: unknown): name is string;
+/**
+ * Resolve the install target and guarantee it stays directly inside
+ * pluginsDir (defence-in-depth against `..`/absolute names even though
+ * isValidConnectorName already rejects them).
+ */
+export declare function safeTarget(pluginsDir: string, name: string): string;
+export interface InstallResult {
+    name: string;
+    version: string | null;
+}
+/**
+ * Install a connector tarball into pluginsDir, fail-closed. Always
+ * verifies the manifest signature + entry integrity against trustRoot
+ * — there is intentionally NO insecure bypass on this path (it's
+ * reachable over HTTP). Throws PluginVerificationError on any failure.
+ */
+export declare function installTarball(opts: {
+    tgzPath: string;
+    pluginsDir: string;
+    trustRootPath: string;
+    expectedName?: string;
+}): InstallResult;

package/dist/connectors/install.js

@@ -0,0 +1,100 @@
+// Shared connector-install core: extract a tarball, verify it
+// fail-closed against a trust root (the SAME crypto as the server
+// loader / omcp CLI — verify.ts), then atomically place it under
+// PLUGINS_DIR. Used by the Web UI install API (and reusable by the
+// CLI). Pure guards are split out for unit testing.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync, mkdtempSync, mkdirSync, rmSync, cpSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { loadTrustRoot, verifyIntegrity, verifyManifestSignature, PluginVerificationError, } from "./verify.js";
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+/** A connector name is safe iff kebab-case ASCII (also blocks traversal). */
+export function isValidConnectorName(name) {
+    return typeof name === "string" && NAME_RE.test(name);
+}
+/**
+ * Resolve the install target and guarantee it stays directly inside
+ * pluginsDir (defence-in-depth against `..`/absolute names even though
+ * isValidConnectorName already rejects them).
+ */
+export function safeTarget(pluginsDir, name) {
+    if (!isValidConnectorName(name))
+        throw new Error(`invalid connector name: ${String(name)}`);
+    const base = resolve(pluginsDir);
+    const target = resolve(base, name);
+    if (target !== join(base, name) || !target.startsWith(base + "/")) {
+        throw new Error("refusing path outside PLUGINS_DIR");
+    }
+    return target;
+}
+function tarExtract(tgz, dest) {
+    const r = spawnSync("tar", ["-xzf", tgz, "-C", dest], { stdio: "pipe" });
+    if (r.status !== 0)
+        throw new Error(`tar extraction failed: ${r.stderr?.toString() || r.status}`);
+}
+function findPluginRoot(base) {
+    for (const dir of [base, ...readdirSync(base).map((e) => join(base, e))]) {
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+            const pkgPath = join(dir, "package.json");
+            if (!existsSync(pkgPath))
+                continue;
+            if (JSON.parse(readFileSync(pkgPath, "utf8")).observabilityMcp?.kind === "connector")
+                return dir;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return null;
+}
+/**
+ * Install a connector tarball into pluginsDir, fail-closed. Always
+ * verifies the manifest signature + entry integrity against trustRoot
+ * — there is intentionally NO insecure bypass on this path (it's
+ * reachable over HTTP). Throws PluginVerificationError on any failure.
+ */
+export function installTarball(opts) {
+    const trustRoot = loadTrustRoot(opts.trustRootPath); // throws if unreadable/bad
+    const work = mkdtempSync(join(tmpdir(), "obsmcp-install-"));
+    try {
+        const stage = join(work, "stage");
+        mkdirSync(stage);
+        tarExtract(opts.tgzPath, stage);
+        const root = findPluginRoot(stage);
+        if (!root)
+            throw new PluginVerificationError("tarball has no connector package.json marker");
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        const marker = pkg.observabilityMcp;
+        const name = marker?.name;
+        if (!isValidConnectorName(name))
+            throw new PluginVerificationError(`invalid connector name in package: ${String(name)}`);
+        if (opts.expectedName && opts.expectedName !== name) {
+            throw new PluginVerificationError(`tarball is '${name}', expected '${opts.expectedName}'`);
+        }
+        const manifestRel = marker.manifest || "./manifest.json";
+        const manifestPath = resolve(root, manifestRel);
+        if (!existsSync(manifestPath))
+            throw new PluginVerificationError(`manifest not found: ${manifestRel}`);
+        const sigPath = manifestPath + ".sig";
+        if (!existsSync(sigPath))
+            throw new PluginVerificationError(`missing manifest signature: ${manifestRel}.sig`);
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        const entryPath = resolve(root, pkg.main || "index.js");
+        // Fail-closed: signature over the manifest + manifest pins the
+        // entry hash. Throws PluginVerificationError on mismatch.
+        verifyManifestSignature(readFileSync(manifestPath), readFileSync(sigPath), trustRoot);
+        verifyIntegrity(entryPath, manifest.integrity);
+        const target = safeTarget(opts.pluginsDir, name);
+        mkdirSync(opts.pluginsDir, { recursive: true });
+        if (existsSync(target))
+            rmSync(target, { recursive: true, force: true });
+        cpSync(root, target, { recursive: true });
+        return { name, version: manifest.version ?? null };
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}

package/dist/connectors/install.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/connectors/install.test.js

@@ -0,0 +1,58 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync, sign as edSign, createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { isValidConnectorName, safeTarget, installTarball } from "./install.js";
+import { PluginVerificationError } from "./verify.js";
+test("isValidConnectorName: kebab only, blocks traversal", () => {
+    assert.ok(isValidConnectorName("datadog"));
+    assert.ok(isValidConnectorName("my-connector9"));
+    for (const bad of ["../evil", "Foo", "a/b", "", "1abc", "a_b", null, 42]) {
+        assert.equal(isValidConnectorName(bad), false);
+    }
+});
+test("safeTarget keeps the path inside pluginsDir", () => {
+    const t = safeTarget("/plugins", "datadog");
+    assert.equal(t, "/plugins/datadog");
+    assert.throws(() => safeTarget("/plugins", "../etc"), /invalid connector name|outside/);
+});
+function mkSignedTarball(dir, name, priv, opts = {}) {
+    const src = join(dir, "src");
+    mkdirSync(src, { recursive: true });
+    writeFileSync(join(src, "index.js"), "export default () => ({});\n");
+    const integ = "sha256-" + createHash("sha256").update(readFileSync(join(src, "index.js"))).digest("base64");
+    const manifest = { schemaVersion: 1, name, displayName: name, version: "1.0.0", description: "x", signalTypes: ["metrics"], integrity: integ };
+    const mb = Buffer.from(JSON.stringify(manifest));
+    writeFileSync(join(src, "manifest.json"), mb);
+    if (!opts.noSig)
+        writeFileSync(join(src, "manifest.json.sig"), edSign(null, mb, priv));
+    writeFileSync(join(src, "package.json"), JSON.stringify({ name, main: "index.js", observabilityMcp: { kind: "connector", name, manifest: "./manifest.json" } }));
+    if (opts.tamper)
+        writeFileSync(join(src, "index.js"), "export default () => ({}); /* tampered */\n");
+    const tgz = join(dir, `${name}-1.0.0.tgz`);
+    const r = spawnSync("tar", ["-czf", tgz, "-C", src, "."]);
+    assert.equal(r.status, 0, "tar failed in test setup");
+    return tgz;
+}
+test("installTarball: verifies + installs; rejects tamper / missing sig / wrong name", () => {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const work = mkdtempSync(join(tmpdir(), "it-"));
+    const pub = join(work, "pub.pem");
+    writeFileSync(pub, publicKey.export({ type: "spki", format: "pem" }));
+    const pluginsDir = join(work, "plugins");
+    const good = mkSignedTarball(join(work, "good"), "datadog", privateKey);
+    const r = installTarball({ tgzPath: good, pluginsDir, trustRootPath: pub });
+    assert.equal(r.name, "datadog");
+    assert.equal(r.version, "1.0.0");
+    assert.ok(existsSync(join(pluginsDir, "datadog", "manifest.json")));
+    const tampered = mkSignedTarball(join(work, "bad"), "datadog", privateKey, { tamper: true });
+    assert.throws(() => installTarball({ tgzPath: tampered, pluginsDir, trustRootPath: pub }), PluginVerificationError);
+    const noSig = mkSignedTarball(join(work, "nosig"), "datadog", privateKey, { noSig: true });
+    assert.throws(() => installTarball({ tgzPath: noSig, pluginsDir, trustRootPath: pub }), /missing manifest signature/);
+    const other = mkSignedTarball(join(work, "other"), "grafana", privateKey);
+    assert.throws(() => installTarball({ tgzPath: other, pluginsDir, trustRootPath: pub, expectedName: "datadog" }), /expected 'datadog'/);
+});

package/dist/connectors/loader.d.ts

@@ -0,0 +1,48 @@
+import type { ObservabilityConnector } from "./interface.js";
+import type { ConnectorFactory, ConnectorManifest } from "../sdk/index.js";
+export interface LoadedConnector {
+    /** Connector type id, e.g. "prometheus". Matches `source.type` in sources.yaml. */
+    name: string;
+    /** Where this connector came from (debug + UI display). */
+    source: "builtin" | "filesystem" | "config";
+    /** Optional metadata for plugins that ship a manifest.json. */
+    manifest?: ConnectorManifest;
+    factory: ConnectorFactory;
+}
+/**
+ * Resolves which connector implementations the server should know about,
+ * applying three sources in order (later overrides earlier):
+ *   1. builtin shim — Prometheus/Loki bundled with the server
+ *   2. filesystem  — every subdir of PLUGINS_DIR with a valid package.json
+ *   3. config-pinned — `plugins:` block in sources.yaml (not yet wired)
+ *
+ * The legacy `connectorFactories` map in registry.ts can be replaced
+ * with this loader's output without changing observable behaviour.
+ */
+export declare class PluginLoader {
+    private connectors;
+    private pluginsDir;
+    private disabled;
+    private verify;
+    private trustRootPath?;
+    private trustRoot?;
+    constructor(opts?: {
+        pluginsDir?: string;
+        disabled?: string[];
+        verify?: boolean;
+        trustRoot?: string;
+    });
+    load(): Promise<void>;
+    list(): LoadedConnector[];
+    get(name: string): LoadedConnector | undefined;
+    has(name: string): boolean;
+    supportedTypes(): string[];
+    /** Create a fresh instance of a connector. Returns undefined for unknown types. */
+    create(name: string): ObservabilityConnector | undefined;
+    private loadBuiltins;
+    private loadFilesystem;
+    private loadFilesystemPlugin;
+    private register;
+}
+export declare function getPluginLoader(): PluginLoader;
+export declare function setPluginLoader(loader: PluginLoader): void;