@thotischner/observability-mcp 1.3.4 → 1.4.1

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createConnection } from "node:net";
+import { existsSync, readFileSync, writeFileSync, mkdtempSync, mkdirSync, rmSync, readdirSync, statSync, cpSync, } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { parseArgs, pickFreePort, composeOverride, resolveCatalogSource, formatPluginList, formatPluginInfo, resolveInstall, splitPassthrough, helmReleaseArgs, HELM_REPO_NAME, HELM_REPO_URL, HELP, } from "./lib.js";
+import { loadTrustRoot, verifyIntegrity, verifyManifestSignature, PluginVerificationError, } from "../connectors/verify.js";
+function pkgVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // dist/cli/index.js → ../../package.json
+        return JSON.parse(readFileSync(join(here, "..", "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function which(bin, args = ["--version"]) {
+    const r = spawnSync(bin, args, { encoding: "utf8" });
+    if (r.status === 0)
+        return (r.stdout || r.stderr || "").trim().split("\n")[0];
+    return null;
+}
+function dockerComposeVersion() {
+    const r = spawnSync("docker", ["compose", "version"], { encoding: "utf8" });
+    return r.status === 0 ? (r.stdout || "").trim().split("\n")[0] : null;
+}
+// Walk up from cwd looking for the repo's docker-compose.yml.
+function findComposeFile() {
+    let dir = process.cwd();
+    for (let i = 0; i < 8; i++) {
+        const f = join(dir, "docker-compose.yml");
+        if (existsSync(f))
+            return f;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+// Walk up from cwd for a checkout's generated catalog.
+function findLocalCatalog() {
+    let dir = process.cwd();
+    for (let i = 0; i < 8; i++) {
+        const f = join(dir, "hub", "catalog", "index.json");
+        if (existsSync(f))
+            return f;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+async function loadCatalog(from) {
+    const src = resolveCatalogSource(from, findLocalCatalog());
+    if (src.kind === "file") {
+        if (!existsSync(src.location))
+            fail(`catalog not found: ${src.location}`);
+        return JSON.parse(readFileSync(src.location, "utf8"));
+    }
+    const r = await fetch(src.location).catch((e) => fail(`fetch failed: ${String(e)}`));
+    if (!r.ok)
+        fail(`catalog HTTP ${r.status} from ${src.location}`);
+    return (await r.json());
+}
+async function plugin(sub, args, flags) {
+    const from = typeof flags.from === "string" ? flags.from : undefined;
+    const json = flags.json === true;
+    // `verify` operates on a local dir — no catalog needed (works offline).
+    if (sub === "verify") {
+        const dir = args[0];
+        if (!dir)
+            fail("usage: omcp plugin verify <dir> --trust-root <pem>");
+        const abs = resolve(dir);
+        if (!existsSync(abs))
+            fail(`directory not found: ${abs}`);
+        verifyPluginDir(abs, flags);
+        return;
+    }
+    const cat = await loadCatalog(from);
+    if (sub === "list") {
+        console.log(json ? JSON.stringify(cat, null, 2) : formatPluginList(cat));
+        return;
+    }
+    if (sub === "info") {
+        const name = args[0];
+        if (!name)
+            fail("usage: omcp plugin info <name>");
+        const c = cat.connectors.find((x) => x.name === name);
+        if (!c)
+            fail(`no connector '${name}' in catalog (try: omcp plugin list)`);
+        console.log(json ? JSON.stringify(c, null, 2) : formatPluginInfo(c));
+        return;
+    }
+    if (sub === "install") {
+        return installPlugin(cat, args[0], flags);
+    }
+    fail(`unknown 'plugin' subcommand: ${sub ?? "(none)"} (list|info|install|verify)`);
+}
+function tarExtract(tgz, dest) {
+    const r = spawnSync("tar", ["-xzf", tgz, "-C", dest], { stdio: "inherit" });
+    if (r.status !== 0)
+        fail(`tar extraction failed for ${tgz}`);
+}
+// Find the dir containing a package.json with the observabilityMcp
+// connector marker (npm pack nests under package/; airgapped tarballs
+// may not).
+function findPluginRoot(base) {
+    const candidates = [base, ...readdirSync(base).map((e) => join(base, e))];
+    for (const dir of candidates) {
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+            const pkgPath = join(dir, "package.json");
+            if (!existsSync(pkgPath))
+                continue;
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            if (pkg.observabilityMcp?.kind === "connector")
+                return dir;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return null;
+}
+// Shared fail-closed verification of an extracted/installed plugin dir.
+// Used by `plugin install` and `plugin verify`. --insecure explicitly
+// opts out; otherwise --trust-root is mandatory.
+function verifyPluginDir(root, flags) {
+    const pkgPath = join(root, "package.json");
+    if (!existsSync(pkgPath))
+        fail(`no package.json in ${root}`);
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (pkg.observabilityMcp?.kind !== "connector")
+        fail("not a connector (observabilityMcp marker)");
+    const manifestRel = pkg.observabilityMcp?.manifest;
+    if (!manifestRel)
+        fail("package.json has no observabilityMcp.manifest");
+    const manifestPath = resolve(root, manifestRel);
+    if (!existsSync(manifestPath))
+        fail(`manifest not found: ${manifestRel}`);
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const entryPath = resolve(root, pkg.main || "index.js");
+    if (flags.insecure === true) {
+        console.warn("WARNING: --insecure — skipping signature + integrity verification.");
+        return;
+    }
+    const trustRootPath = typeof flags["trust-root"] === "string" ? flags["trust-root"] : undefined;
+    if (!trustRootPath) {
+        fail("verification required: pass --trust-root <pem> (or --insecure to explicitly opt out)");
+    }
+    const sigPath = manifestPath + ".sig";
+    if (!existsSync(sigPath))
+        fail(`missing manifest signature: ${manifestRel}.sig`);
+    try {
+        const trustRoot = loadTrustRoot(trustRootPath);
+        verifyManifestSignature(readFileSync(manifestPath), readFileSync(sigPath), trustRoot);
+        verifyIntegrity(entryPath, manifest.integrity);
+    }
+    catch (e) {
+        const msg = e instanceof PluginVerificationError ? e.message : String(e);
+        fail(`verification failed (fail-closed): ${msg}`);
+    }
+    console.log(`signature + integrity OK (${pkg.observabilityMcp.name}@${manifest.version ?? "?"})`);
+}
+async function installPlugin(cat, ref, flags) {
+    if (!ref)
+        fail("usage: omcp plugin install <name>[@version]");
+    let r;
+    try {
+        r = resolveInstall(cat, ref);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+    if (r.builtin) {
+        console.log(`'${r.name}' is builtin — it ships in the server image, no install needed.`);
+        return;
+    }
+    const offlineDir = typeof flags["offline-dir"] === "string" ? flags["offline-dir"] : undefined;
+    const dest = resolve(typeof flags.dest === "string" ? flags.dest : process.env.PLUGINS_DIR ?? "./plugins");
+    const targetDir = join(dest, r.name);
+    if (existsSync(targetDir) && flags.force !== true) {
+        fail(`${targetDir} already exists (pass --force to overwrite)`);
+    }
+    const work = mkdtempSync(join(tmpdir(), "omcp-inst-"));
+    const tgz = join(work, "plugin.tgz");
+    if (offlineDir) {
+        const local = join(offlineDir, `${r.name}-${r.version}.tgz`);
+        if (!existsSync(local))
+            fail(`offline tarball not found: ${local}`);
+        cpSync(local, tgz);
+    }
+    else {
+        if (!r.tarballUrl)
+            fail(`catalog entry for ${r.name}@${r.version} has no tarballUrl`);
+        const resp = await fetch(r.tarballUrl).catch((e) => fail(`download failed: ${String(e)}`));
+        if (!resp.ok)
+            fail(`tarball HTTP ${resp.status}`);
+        writeFileSync(tgz, Buffer.from(await resp.arrayBuffer()));
+    }
+    const stage = join(work, "stage");
+    mkdirSync(stage);
+    tarExtract(tgz, stage);
+    const root = findPluginRoot(stage);
+    if (!root)
+        fail("no connector package.json (observabilityMcp marker) in tarball");
+    verifyPluginDir(root, flags);
+    mkdirSync(dest, { recursive: true });
+    if (existsSync(targetDir))
+        rmSync(targetDir, { recursive: true, force: true });
+    cpSync(root, targetDir, { recursive: true });
+    rmSync(work, { recursive: true, force: true });
+    console.log(`installed ${r.name}@${r.version} → ${targetDir}`);
+}
+function portInUse(port, host = "127.0.0.1") {
+    return new Promise((resolve) => {
+        const s = createConnection({ port, host });
+        const done = (v) => {
+            s.destroy();
+            resolve(v);
+        };
+        s.setTimeout(400);
+        s.once("connect", () => done(true));
+        s.once("timeout", () => done(false));
+        s.once("error", () => done(false));
+    });
+}
+function fail(msg) {
+    console.error("error: " + msg);
+    process.exit(1);
+}
+async function doctor(json) {
+    const checks = {
+        node: process.version,
+        docker: which("docker"),
+        "docker compose": dockerComposeVersion(),
+        helm: which("helm", ["version", "--short"]),
+        "compose file": findComposeFile() ?? null,
+    };
+    if (json) {
+        console.log(JSON.stringify(checks, null, 2));
+    }
+    else {
+        for (const [k, v] of Object.entries(checks)) {
+            const ok = v != null;
+            console.log(`${ok ? "ok  " : "MISS"}  ${k.padEnd(16)} ${ok ? v : "(not found)"}`);
+        }
+    }
+    const required = ["docker", "docker compose"];
+    if (required.some((k) => checks[k] == null)) {
+        fail("missing required tooling (docker + docker compose)");
+    }
+}
+async function demo(sub) {
+    const compose = findComposeFile();
+    if (!compose)
+        fail("docker-compose.yml not found (run from an observability-mcp checkout)");
+    const root = dirname(compose);
+    const baseArgs = ["compose", "-f", compose];
+    if (sub === "status") {
+        run("docker", [...baseArgs, "--profile", "demo", "ps"], root);
+        return;
+    }
+    if (sub === "down") {
+        run("docker", [...baseArgs, "--profile", "demo", "down", "-v"], root);
+        return;
+    }
+    if (sub !== "up")
+        fail(`unknown 'demo' subcommand: ${sub ?? "(none)"} (up|down|status)`);
+    // Auto-pick free host ports for the two services that commonly clash.
+    const wanted = [
+        { service: "mcp-server", container: 3000 },
+        { service: "loki", container: 3100 },
+    ];
+    const remaps = [];
+    for (const w of wanted) {
+        const busy = await portInUse(w.container);
+        let host = w.container;
+        if (busy) {
+            const used = new Set();
+            host = pickFreePort(w.container + 1, (p) => used.has(p));
+            // Probe sequentially; mark scanned-busy ports so pickFreePort skips.
+            for (let p = w.container + 1; p < w.container + 50; p++) {
+                if (await portInUse(p))
+                    used.add(p);
+                else {
+                    host = p;
+                    break;
+                }
+            }
+            console.log(`port ${w.container} busy → ${w.service} mapped to host ${host}`);
+        }
+        remaps.push({ service: w.service, host, container: w.container });
+    }
+    const args = [...baseArgs];
+    const mcp = remaps.find((r) => r.service === "mcp-server");
+    const needsOverride = remaps.some((r) => r.host !== r.container);
+    if (needsOverride) {
+        const dir = mkdtempSync(join(tmpdir(), "omcp-"));
+        const ovr = join(dir, "override.yml");
+        writeFileSync(ovr, composeOverride(remaps));
+        args.push("-f", ovr);
+    }
+    args.push("--profile", "demo", "up", "--build", "-d");
+    const code = run("docker", args, root);
+    if (code === 0) {
+        console.log(`\ndemo stack up. Web UI / MCP: http://localhost:${mcp.host}  (/mcp, /healthz)`);
+        console.log("Stop with: omcp demo down");
+    }
+    process.exit(code);
+}
+function helm(sub, release, passthrough) {
+    if (sub !== "install" && sub !== "upgrade") {
+        fail(`unknown 'helm' subcommand: ${sub ?? "(none)"} (install|upgrade)`);
+    }
+    if (!which("helm", ["version", "--short"])) {
+        fail("helm not found on PATH (see: https://helm.sh/docs/intro/install/)");
+    }
+    const cwd = process.cwd();
+    // Idempotent: --force-update tolerates an existing repo entry.
+    if (run("helm", ["repo", "add", HELM_REPO_NAME, HELM_REPO_URL, "--force-update"], cwd) !== 0) {
+        fail("helm repo add failed");
+    }
+    if (run("helm", ["repo", "update", HELM_REPO_NAME], cwd) !== 0) {
+        fail("helm repo update failed");
+    }
+    const args = helmReleaseArgs(sub, release, passthrough);
+    const code = run("helm", args, cwd);
+    if (code === 0) {
+        console.log(`\nhelm ${sub} ok: release '${release}' from the signed ${HELM_REPO_NAME} chart.`);
+    }
+    process.exit(code);
+}
+function run(cmd, args, cwd) {
+    const r = spawnSync(cmd, args, { cwd, stdio: "inherit" });
+    return r.status ?? 1;
+}
+async function main() {
+    const { argv: pre, passthrough } = splitPassthrough(process.argv.slice(2));
+    const { command, sub, flags, positionals } = parseArgs(pre);
+    const json = flags.json === true;
+    switch (command) {
+        case "":
+        case "help":
+        case "--help":
+            console.log(HELP);
+            return;
+        case "version":
+        case "--version":
+            console.log(`omcp ${pkgVersion()}`);
+            return;
+        case "doctor":
+            return doctor(json);
+        case "demo":
+            return demo(sub);
+        case "plugin":
+            return plugin(sub, positionals, flags);
+        case "helm":
+            return helm(sub, positionals[0] ?? "observability-mcp", passthrough);
+        default:
+            fail(`unknown command: ${command}\n\n${HELP}`);
+    }
+}
+main().catch((e) => fail(e instanceof Error ? e.message : String(e)));

package/dist/cli/lib.d.ts

@@ -0,0 +1,95 @@
+export interface ParsedArgs {
+    command: string;
+    sub?: string;
+    flags: Record<string, string | boolean>;
+    positionals: string[];
+}
+/** Minimal argv parser: `omcp <command> [sub] [positionals] [--flag[=val]] [-f val]`. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Given a desired port and a predicate that says whether a port is in
+ * use, return the first free port at or after `desired` (bounded scan).
+ */
+export declare function pickFreePort(desired: number, inUse: (p: number) => boolean, span?: number): number;
+/**
+ * Build a docker-compose override that remaps the host side of the
+ * given service ports. Uses the `!override` tag so it replaces (not
+ * appends to) the base `ports:` list.
+ */
+export declare function composeOverride(remaps: Array<{
+    service: string;
+    host: number;
+    container: number;
+}>): string;
+export declare const DEFAULT_CATALOG_URL = "https://thotischner.github.io/observability-mcp/hub/index.json";
+export interface CatalogVersion {
+    version: string;
+    releasedAt?: string;
+    serverCompat?: string;
+    tarballUrl?: string;
+    signatureUrl?: string;
+    manifestUrl?: string;
+    integrity?: string;
+    changelog?: string;
+}
+export interface CatalogConnector {
+    name: string;
+    displayName: string;
+    description: string;
+    tier: string;
+    builtin?: boolean;
+    signalTypes: string[];
+    latest?: string;
+    versions: CatalogVersion[];
+}
+export interface Catalog {
+    catalogVersion: number;
+    connectors: CatalogConnector[];
+}
+/**
+ * Decide where to read the catalog from, in priority order:
+ *   1. explicit `from` (a URL or a filesystem path)
+ *   2. a local checkout's hub/catalog/index.json (when localPath exists)
+ *   3. the public Pages catalog
+ */
+export declare function resolveCatalogSource(from: string | undefined, localPath: string | null): {
+    kind: "url" | "file";
+    location: string;
+};
+export declare function formatPluginList(cat: Catalog): string;
+export declare function formatPluginInfo(c: CatalogConnector): string;
+/** Split "name" or "name@1.2.3" into parts. Throws on a malformed ref. */
+export declare function parsePluginRef(ref: string): {
+    name: string;
+    version?: string;
+};
+export interface ResolvedInstall {
+    name: string;
+    version: string;
+    builtin: boolean;
+    tarballUrl?: string;
+    signatureUrl?: string;
+    manifestUrl?: string;
+    integrity?: string;
+}
+/**
+ * Resolve a catalog + ref into the concrete artifact to install.
+ * Returns {builtin:true} for image-bundled connectors (caller should
+ * no-op). Throws if the connector/version is unknown.
+ */
+export declare function resolveInstall(cat: Catalog, ref: string): ResolvedInstall;
+export declare const HELM_REPO_NAME = "observability-mcp";
+export declare const HELM_REPO_URL = "https://thotischner.github.io/observability-mcp/";
+export declare const HELM_CHART = "observability-mcp/observability-mcp";
+/**
+ * Split argv at the first standalone "--": everything after it is
+ * passed verbatim to the wrapped tool (helm). Keeps omcp from having to
+ * re-implement helm's flag grammar (repeatable --set, -n, -f, ...).
+ */
+export declare function splitPassthrough(argv: string[]): {
+    argv: string[];
+    passthrough: string[];
+};
+/** The helm argv for the install/upgrade step (repo add/update are fixed). */
+export declare function helmReleaseArgs(action: "install" | "upgrade", release: string, passthrough: string[]): string[];
+export declare const HELP = "omcp \u2014 observability-mcp control CLI\n\nUsage:\n  omcp version                 Print CLI + server package version\n  omcp doctor                  Check the local toolchain (docker, compose, helm, node)\n  omcp demo up                 Start the full demo stack (auto-picks free host ports)\n  omcp demo down               Stop and remove the demo stack\n  omcp demo status             Show demo container status\n  omcp plugin list             List connectors from the hub catalog\n  omcp plugin info <name>      Show one connector's versions + verification info\n  omcp plugin install <ref>    Install name[@version]: download, verify, extract\n  omcp plugin verify <dir>     Verify an installed plugin dir against a trust root\n  omcp helm install [release]  helm repo add+update, then install the signed chart\n  omcp helm upgrade [release]  Same, as 'helm upgrade --install'\n  omcp help                    Show this help\n\nPass extra helm flags after a literal --, e.g.:\n  omcp helm upgrade obs -- -n monitoring --set sources.prometheusUrl=http://prom:9090\n\nFlags:\n  --json                       Machine-readable output (doctor, status, plugin)\n  --from <url|path>            Catalog source (default: local checkout or the public hub)\n  --offline-dir <dir>          Airgapped: read <name>-<ver>.tgz[.sig] + manifest from <dir>\n  --trust-root <pem>           Verify signature+integrity against this PEM (fail-closed)\n  --insecure                   Skip verification (NOT recommended; explicit opt-out)\n  --dest <dir>                 Install target (default: $PLUGINS_DIR or ./plugins)\n  --force                      Overwrite an existing install dir\n";

package/dist/cli/lib.js

@@ -0,0 +1,185 @@
+// Pure, IO-free helpers for the omcp CLI so they can be unit-tested
+// without spawning docker or touching the filesystem.
+/** Minimal argv parser: `omcp <command> [sub] [positionals] [--flag[=val]] [-f val]`. */
+export function parseArgs(argv) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            if (eq !== -1)
+                flags[a.slice(2, eq)] = a.slice(eq + 1);
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("-"))
+                flags[a.slice(2)] = argv[++i];
+            else
+                flags[a.slice(2)] = true;
+        }
+        else if (a.startsWith("-") && a.length > 1) {
+            if (i + 1 < argv.length && !argv[i + 1].startsWith("-"))
+                flags[a.slice(1)] = argv[++i];
+            else
+                flags[a.slice(1)] = true;
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { command: rest[0] ?? "", sub: rest[1], flags, positionals: rest.slice(2) };
+}
+/**
+ * Given a desired port and a predicate that says whether a port is in
+ * use, return the first free port at or after `desired` (bounded scan).
+ */
+export function pickFreePort(desired, inUse, span = 50) {
+    for (let p = desired; p < desired + span; p++) {
+        if (!inUse(p))
+            return p;
+    }
+    throw new Error(`no free port in [${desired}, ${desired + span})`);
+}
+/**
+ * Build a docker-compose override that remaps the host side of the
+ * given service ports. Uses the `!override` tag so it replaces (not
+ * appends to) the base `ports:` list.
+ */
+export function composeOverride(remaps) {
+    const services = remaps
+        .map((r) => `  ${r.service}:\n    ports: !override\n      - "${r.host}:${r.container}"`)
+        .join("\n");
+    return `services:\n${services}\n`;
+}
+export const DEFAULT_CATALOG_URL = "https://thotischner.github.io/observability-mcp/hub/index.json";
+/**
+ * Decide where to read the catalog from, in priority order:
+ *   1. explicit `from` (a URL or a filesystem path)
+ *   2. a local checkout's hub/catalog/index.json (when localPath exists)
+ *   3. the public Pages catalog
+ */
+export function resolveCatalogSource(from, localPath) {
+    if (from) {
+        return /^https?:\/\//.test(from)
+            ? { kind: "url", location: from }
+            : { kind: "file", location: from };
+    }
+    if (localPath)
+        return { kind: "file", location: localPath };
+    return { kind: "url", location: DEFAULT_CATALOG_URL };
+}
+export function formatPluginList(cat) {
+    const rows = cat.connectors
+        .slice()
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((c) => {
+        const latest = c.latest ?? c.versions[0]?.version ?? "—";
+        const flags = [c.builtin ? "builtin" : "", c.tier].filter(Boolean).join(",");
+        return [c.name, latest, c.signalTypes.join("+"), flags];
+    });
+    const head = ["NAME", "LATEST", "SIGNALS", "TIER"];
+    const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const line = (cols) => cols.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+    return [line(head), ...rows.map(line)].join("\n");
+}
+export function formatPluginInfo(c) {
+    const out = [];
+    out.push(`${c.displayName}  (${c.name})`);
+    out.push(`  tier:      ${c.tier}${c.builtin ? " · builtin (ships in the server image)" : ""}`);
+    out.push(`  signals:   ${c.signalTypes.join(", ")}`);
+    out.push(`  ${c.description}`);
+    out.push(`  versions:`);
+    for (const v of c.versions) {
+        out.push(`    - ${v.version}${v.releasedAt ? ` (${v.releasedAt})` : ""}${v.serverCompat ? ` · server ${v.serverCompat}` : ""}`);
+        if (v.integrity)
+            out.push(`      integrity: ${v.integrity}`);
+        if (v.signatureUrl)
+            out.push(`      signature: ${v.signatureUrl}`);
+        if (v.tarballUrl)
+            out.push(`      tarball:   ${v.tarballUrl}`);
+        if (v.changelog)
+            out.push(`      changelog: ${v.changelog}`);
+    }
+    return out.join("\n");
+}
+/** Split "name" or "name@1.2.3" into parts. Throws on a malformed ref. */
+export function parsePluginRef(ref) {
+    const m = ref.match(/^([a-z][a-z0-9-]*)(?:@(\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?))?$/);
+    if (!m)
+        throw new Error(`invalid plugin ref '${ref}' (expected name or name@x.y.z)`);
+    return { name: m[1], version: m[2] };
+}
+/**
+ * Resolve a catalog + ref into the concrete artifact to install.
+ * Returns {builtin:true} for image-bundled connectors (caller should
+ * no-op). Throws if the connector/version is unknown.
+ */
+export function resolveInstall(cat, ref) {
+    const { name, version } = parsePluginRef(ref);
+    const c = cat.connectors.find((x) => x.name === name);
+    if (!c)
+        throw new Error(`no connector '${name}' in catalog (try: omcp plugin list)`);
+    if (c.builtin)
+        return { name, version: version ?? c.latest ?? "", builtin: true };
+    const v = version
+        ? c.versions.find((x) => x.version === version)
+        : c.versions.find((x) => x.version === (c.latest ?? c.versions[0]?.version)) ?? c.versions[0];
+    if (!v)
+        throw new Error(`version '${version}' not found for '${name}'`);
+    return {
+        name,
+        version: v.version,
+        builtin: false,
+        tarballUrl: v.tarballUrl,
+        signatureUrl: v.signatureUrl,
+        manifestUrl: v.manifestUrl,
+        integrity: v.integrity,
+    };
+}
+export const HELM_REPO_NAME = "observability-mcp";
+export const HELM_REPO_URL = "https://thotischner.github.io/observability-mcp/";
+export const HELM_CHART = "observability-mcp/observability-mcp";
+/**
+ * Split argv at the first standalone "--": everything after it is
+ * passed verbatim to the wrapped tool (helm). Keeps omcp from having to
+ * re-implement helm's flag grammar (repeatable --set, -n, -f, ...).
+ */
+export function splitPassthrough(argv) {
+    const i = argv.indexOf("--");
+    if (i === -1)
+        return { argv, passthrough: [] };
+    return { argv: argv.slice(0, i), passthrough: argv.slice(i + 1) };
+}
+/** The helm argv for the install/upgrade step (repo add/update are fixed). */
+export function helmReleaseArgs(action, release, passthrough) {
+    const head = action === "upgrade"
+        ? ["upgrade", "--install", release, HELM_CHART]
+        : ["install", release, HELM_CHART];
+    return [...head, ...passthrough];
+}
+export const HELP = `omcp — observability-mcp control CLI
+
+Usage:
+  omcp version                 Print CLI + server package version
+  omcp doctor                  Check the local toolchain (docker, compose, helm, node)
+  omcp demo up                 Start the full demo stack (auto-picks free host ports)
+  omcp demo down               Stop and remove the demo stack
+  omcp demo status             Show demo container status
+  omcp plugin list             List connectors from the hub catalog
+  omcp plugin info <name>      Show one connector's versions + verification info
+  omcp plugin install <ref>    Install name[@version]: download, verify, extract
+  omcp plugin verify <dir>     Verify an installed plugin dir against a trust root
+  omcp helm install [release]  helm repo add+update, then install the signed chart
+  omcp helm upgrade [release]  Same, as 'helm upgrade --install'
+  omcp help                    Show this help
+
+Pass extra helm flags after a literal --, e.g.:
+  omcp helm upgrade obs -- -n monitoring --set sources.prometheusUrl=http://prom:9090
+
+Flags:
+  --json                       Machine-readable output (doctor, status, plugin)
+  --from <url|path>            Catalog source (default: local checkout or the public hub)
+  --offline-dir <dir>          Airgapped: read <name>-<ver>.tgz[.sig] + manifest from <dir>
+  --trust-root <pem>           Verify signature+integrity against this PEM (fail-closed)
+  --insecure                   Skip verification (NOT recommended; explicit opt-out)
+  --dest <dir>                 Install target (default: $PLUGINS_DIR or ./plugins)
+  --force                      Overwrite an existing install dir
+`;

package/dist/cli/lib.test.d.ts

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