@proofofwork-agency/toolpin 0.2.3

package/dist/installed.js

@@ -0,0 +1,405 @@
+import { doctorLockfile, readInstalledServerConfig } from "./doctor.js";
+import { installServerConfig, removeServerConfig, resolveConfigTarget } from "./install.js";
+import { listInstalledServers } from "./inventory.js";
+import { buildInstallPlan, lockKey, readLockfile, removeLockfileEntry, writeLockfile } from "./plan.js";
+import { enforcePolicy } from "./policy.js";
+import { testInstalledClientConfig } from "./tester.js";
+import { verifyServer } from "./verify.js";
+import { compareVersionStatus, compareVersionish } from "./versions.js";
+export async function loadInstalledServerStates(options) {
+    const scope = options.scope ?? "all";
+    const [inventory, doctor] = await Promise.all([
+        listInstalledServers({ scope, client: options.client }),
+        doctorLockfile("mcp-lock.json", scope).catch(() => undefined),
+    ]);
+    const issues = doctor?.issues ?? [];
+    const rows = inventory.entries.map((entry) => {
+        const locked = findLockedPlan(options.lockfile, entry.serverName, entry.client);
+        const match = resolveInstalledRegistryMatch(options.servers, entry.serverName, locked?.version);
+        const registryMatch = match.registryMatch ?? (locked ? "exact" : undefined);
+        const testResult = options.tests?.[installedId(entry.serverName, entry.client, entry.scope)];
+        const lockDrift = issues.some((issue) => issueMatchesInstalled(issue, entry.serverName, entry.client, entry.scope));
+        const versionDelta = locked?.version && match.latestVersion ? compareVersionStatus(match.latestVersion, locked.version) : undefined;
+        const updateAvailable = versionDelta !== undefined && versionDelta > 0;
+        const lifecycleAction = lifecycleActionFor({ locked: Boolean(locked), updateAvailable, updateServer: match.updateServer, registryMatch });
+        const canTest = entry.client !== "zed";
+        const runningStatus = testResult?.ok
+            ? "reachable"
+            : lockDrift || updateAvailable
+                ? "stale"
+                : testResult
+                    ? "unknown"
+                    : "not_checked";
+        const issue = lockDrift
+            ? issues.find((candidate) => issueMatchesInstalled(candidate, entry.serverName, entry.client, entry.scope))?.message
+            : match.ambiguousCandidates?.length
+                ? `ambiguous registry alias match: ${match.ambiguousCandidates.join(", ")}`
+                : undefined;
+        return {
+            id: installedId(entry.serverName, entry.client, entry.scope),
+            client: entry.client,
+            scope: entry.scope,
+            file: entry.file,
+            serverName: entry.serverName,
+            installed: true,
+            locked: Boolean(locked),
+            lockDrift,
+            lockedVersion: locked?.version,
+            currentVersion: locked?.version,
+            latestVersion: match.latestVersion ?? locked?.version,
+            updateAvailable,
+            source: locked?.resolved?.source,
+            canUpdate: lifecycleAction !== "none",
+            canDelete: true,
+            canTest,
+            registryMatch,
+            registryStatus: (registryMatch ?? "none"),
+            lifecycleAction,
+            testSource: (canTest ? "config" : "none"),
+            runningStatus,
+            testResult,
+            installableServer: match.currentServer,
+            updateServer: match.updateServer,
+            issue,
+            registryCandidates: match.ambiguousCandidates,
+        };
+    });
+    if (options.lockfile) {
+        const installedKeys = new Set(rows.map((row) => installedId(row.serverName, row.client, row.scope)));
+        for (const locked of Object.values(options.lockfile.servers)) {
+            const lockedScope = locked.scope ?? "project";
+            if (scope !== "all" && lockedScope !== scope)
+                continue;
+            if (options.client && options.client !== "all" && locked.client !== options.client)
+                continue;
+            const id = installedId(locked.name, locked.client, lockedScope);
+            if (installedKeys.has(id))
+                continue;
+            const match = resolveInstalledRegistryMatch(options.servers, locked.name, locked.version);
+            const target = safeConfigTarget(locked.client, lockedScope);
+            rows.push({
+                id,
+                client: locked.client,
+                scope: lockedScope,
+                file: target?.file ?? "missing client config",
+                serverName: locked.name,
+                installed: false,
+                locked: true,
+                lockDrift: true,
+                lockedVersion: locked.version,
+                currentVersion: undefined,
+                latestVersion: match.latestVersion ?? locked.version,
+                updateAvailable: false,
+                source: locked.resolved?.source,
+                canUpdate: false,
+                canDelete: true,
+                canTest: false,
+                registryMatch: match.registryMatch,
+                registryStatus: (match.registryMatch ?? "none"),
+                lifecycleAction: "none",
+                testSource: "none",
+                runningStatus: "stale",
+                installableServer: match.currentServer,
+                updateServer: match.updateServer,
+                issue: "locked in mcp-lock.json but missing from checked client config",
+                registryCandidates: match.ambiguousCandidates,
+            });
+        }
+    }
+    return rows.sort((left, right) => left.scope.localeCompare(right.scope)
+        || left.client.localeCompare(right.client)
+        || left.serverName.localeCompare(right.serverName)
+        || left.file.localeCompare(right.file));
+}
+export async function testInstalledServer(options) {
+    const target = await getInstalledConfig(options.serverName, options.client, options.scope);
+    return testInstalledClientConfig(options.serverName, target.config, options.timeoutMs ?? 15000);
+}
+export async function adoptInstalledServer(options) {
+    const lockfilePath = options.lockfilePath ?? "mcp-lock.json";
+    const row = await getInstalledLifecycleRow(options.installedName, options.client, options.scope, options.servers, lockfilePath);
+    if (row.locked)
+        throw new Error(`${row.serverName} is already locked for ${row.client}; use \`toolpin update ${row.serverName} --client ${row.client} --scope ${row.scope}\`.`);
+    if (row.registryCandidates?.length) {
+        throw new Error(`Ambiguous registry alias match for ${row.serverName}: ${row.registryCandidates.join(", ")}`);
+    }
+    if (row.lifecycleAction !== "adopt" || !row.updateServer) {
+        throw new Error(`No adoptable registry match found for ${row.serverName}.`);
+    }
+    return mutateInstalledRow(row, row.updateServer, "adopt", options);
+}
+export async function updateInstalledServer(options) {
+    const lockfilePath = options.lockfilePath ?? "mcp-lock.json";
+    const row = await getInstalledLifecycleRow(options.serverName, options.client, options.scope, options.servers, lockfilePath);
+    if (!row.locked)
+        throw new Error(`${row.serverName} is not locked for ${row.client}; use \`toolpin adopt ${row.serverName} --client ${row.client} --scope ${row.scope}\` if you want to lock a registry match.`);
+    if (row.registryCandidates?.length) {
+        throw new Error(`Ambiguous registry alias match for ${row.serverName}: ${row.registryCandidates.join(", ")}`);
+    }
+    const targetServer = options.version
+        ? resolveInstalledRegistryVersion(options.servers, row, options.version)
+        : row.updateServer;
+    if (!targetServer) {
+        throw new Error(`No locked update is available for ${row.serverName}.`);
+    }
+    return mutateInstalledRow(row, targetServer, "update", options);
+}
+export async function updateAllInstalledServers(options) {
+    const lockfilePath = options.lockfilePath ?? "mcp-lock.json";
+    const lockfile = await readLockfile(lockfilePath).catch(() => undefined);
+    const rows = await loadInstalledServerStates({
+        servers: options.servers,
+        lockfile,
+        scope: options.scope,
+        client: options.client,
+    });
+    const updated = [];
+    const skippedAdoptable = [];
+    const skipped = [];
+    for (const row of rows) {
+        if (row.lifecycleAction === "adopt" && row.updateServer) {
+            skippedAdoptable.push({ serverName: row.serverName, client: row.client, scope: row.scope, targetName: row.updateServer.name });
+            continue;
+        }
+        if (row.lifecycleAction !== "update" || !row.updateServer) {
+            skipped.push({ serverName: row.serverName, client: row.client, scope: row.scope, reason: row.locked ? "current" : "unlocked/no-registry-match" });
+            continue;
+        }
+        updated.push(await mutateInstalledRow(row, row.updateServer, "update", options));
+    }
+    return {
+        dryRun: options.dryRun === true,
+        scope: options.scope,
+        client: options.client,
+        updated,
+        skippedAdoptable,
+        skipped,
+    };
+}
+export function installedId(serverName, client, scope) {
+    return `${scope}:${client}:${serverName}`;
+}
+function lifecycleActionFor(input) {
+    if (!input.updateServer?.installable || !input.registryMatch)
+        return "none";
+    if (input.locked)
+        return input.updateAvailable ? "update" : "none";
+    return "adopt";
+}
+function safeConfigTarget(client, scope) {
+    try {
+        return resolveConfigTarget(client, scope);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function getInstalledLifecycleRow(serverName, client, scope, servers, lockfilePath) {
+    const lockfile = await readLockfile(lockfilePath).catch(() => undefined);
+    const rows = await loadInstalledServerStates({ servers, lockfile, scope, client });
+    const row = rows.find((candidate) => candidate.serverName === serverName && candidate.client === client && candidate.scope === scope);
+    if (!row) {
+        throw new Error(`No installed config entry found for ${serverName} in ${client} ${scope} config.`);
+    }
+    return row;
+}
+async function mutateInstalledRow(row, server, action, options) {
+    const lockfilePath = options.lockfilePath ?? "mcp-lock.json";
+    const planned = mutationPlan(row, server, action, lockfilePath);
+    const dryRun = options.dryRun === true;
+    const { plan, verification } = await buildCheckedPlan(server, row.client, row.scope, options);
+    if (dryRun) {
+        return {
+            action,
+            dryRun,
+            serverName: row.serverName,
+            targetName: server.name,
+            client: row.client,
+            scope: row.scope,
+            fromVersion: row.lockedVersion,
+            toVersion: server.version,
+            lockfilePath,
+            lockfileWritten: false,
+            verification,
+            planned,
+        };
+    }
+    let removedAlias;
+    if (row.serverName !== server.name) {
+        removedAlias = await removeServerConfig(row.serverName, row.client, row.scope);
+        await removeLockfileEntry(row.serverName, row.client, lockfilePath);
+    }
+    const config = await installServerConfig(server, row.client, row.scope);
+    await writeLockfile(plan, lockfilePath, lockKey(server.name, row.client));
+    return {
+        action,
+        dryRun,
+        serverName: row.serverName,
+        targetName: server.name,
+        client: row.client,
+        scope: row.scope,
+        fromVersion: row.lockedVersion,
+        toVersion: server.version,
+        removedAlias,
+        config,
+        lockfilePath,
+        lockfileWritten: true,
+        verification,
+        planned,
+    };
+}
+async function buildCheckedPlan(server, client, scope, options) {
+    let capabilityManifest;
+    let verification;
+    if (options.verify) {
+        verification = await verifyServer(server, {
+            liveRemoteProbe: true,
+            livePackageProbe: true,
+            timeoutMs: options.timeoutMs ?? 15000,
+            requireVerified: options.requireVerified === true,
+        });
+        if (!verification.ok) {
+            throw new Error([
+                `${server.name} failed verification.`,
+                ...verification.issues.map((issue) => `- ${issue.severity}: ${issue.code}: ${issue.message}`),
+            ].join("\n"));
+        }
+        capabilityManifest = verification.capabilityManifest;
+    }
+    const plan = buildInstallPlan(server, client, { capabilityManifest, verificationReport: verification, scope });
+    if (options.enforcePolicy !== false) {
+        const report = await enforcePolicy(plan, options.policyPath ?? ".toolpin/policy.json");
+        if (!report.ok) {
+            throw new Error([
+                `Lifecycle action refused by policy ${options.policyPath ?? ".toolpin/policy.json"}.`,
+                ...report.issues.map((issue) => `- ${issue.code}: ${issue.message}`),
+            ].join("\n"));
+        }
+    }
+    return { plan, verification };
+}
+async function getInstalledConfig(serverName, client, scope) {
+    let target;
+    try {
+        target = resolveConfigTarget(client, scope);
+    }
+    catch (error) {
+        throw new Error(`Unsupported ${client} ${scope} target: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const installedConfig = await readInstalledServerConfig(target.file, serverName, client);
+    if (installedConfig.kind === "missing") {
+        throw new Error(`Installed config entry ${serverName} is missing from ${target.file}.`);
+    }
+    if (installedConfig.kind === "unreadable") {
+        throw new Error(installedConfig.message);
+    }
+    return { file: target.file, config: installedConfig.config };
+}
+function mutationPlan(row, server, action, lockfilePath) {
+    return [
+        `${action} ${row.serverName} (${row.client}/${row.scope})`,
+        row.serverName !== server.name ? `remove installed alias ${row.serverName}` : `keep installed name ${row.serverName}`,
+        `write registry target ${server.name}@${server.version}`,
+        `write lockfile entry ${lockKey(server.name, row.client)} to ${lockfilePath}`,
+    ];
+}
+function resolveInstalledRegistryMatch(servers, installedName, currentVersion) {
+    const candidates = matchingServers(servers, installedName);
+    if (!candidates.length)
+        return {};
+    const exact = candidates.filter((server) => server.name === installedName);
+    const pool = exact.length ? exact : candidates;
+    const names = [...new Set(pool.map((server) => server.name))].sort();
+    if (!exact.length && names.length > 1) {
+        return { ambiguousCandidates: names };
+    }
+    const updateServer = bestServer(pool);
+    const currentServer = currentVersion
+        ? pool.find((server) => server.version === currentVersion) ?? updateServer
+        : updateServer;
+    if (!updateServer)
+        return {};
+    return {
+        registryMatch: updateServer.name === installedName ? "exact" : "alias",
+        latestVersion: updateServer.version,
+        currentServer,
+        updateServer,
+    };
+}
+function resolveInstalledRegistryVersion(servers, row, version) {
+    const pool = matchingServers(servers, row.serverName)
+        .filter((server) => !row.updateServer || server.name === row.updateServer.name);
+    const server = pool.find((candidate) => candidate.version === version);
+    if (!server) {
+        const known = pool.map((candidate) => candidate.version).filter(Boolean).join(", ");
+        throw new Error(`No installable registry version ${version} found for ${row.serverName}.${known ? ` Known versions: ${known}.` : ""}`);
+    }
+    return server;
+}
+function findLockedPlan(lockfile, serverName, client) {
+    const keyed = lockfile?.servers[lockKey(serverName, client)];
+    const legacy = lockfile?.servers[serverName];
+    return keyed ?? (legacy?.client === client ? legacy : undefined);
+}
+function bestServer(servers) {
+    return servers.reduce((best, candidate) => {
+        if (!best)
+            return candidate;
+        if (candidate.isLatest && !best.isLatest)
+            return candidate;
+        if (candidate.isLatest === best.isLatest && compareVersionish(candidate.version, best.version) > 0)
+            return candidate;
+        return best;
+    }, undefined);
+}
+function matchingServers(servers, installedName) {
+    const normalized = normalizeName(installedName);
+    return servers
+        .filter((server) => server.installable && serverAliases(server).has(normalized))
+        .sort((left, right) => matchWeight(left, installedName) - matchWeight(right, installedName)
+        || right.isLatest.toString().localeCompare(left.isLatest.toString())
+        || compareVersionish(right.version, left.version)
+        || left.name.localeCompare(right.name));
+}
+function matchWeight(server, installedName) {
+    if (server.name === installedName)
+        return 0;
+    const normalized = normalizeName(installedName);
+    if (normalizeName(server.name.split("/").pop() ?? "") === normalized)
+        return 1;
+    if (normalizeName(server.title) === normalized)
+        return 2;
+    return 3;
+}
+function serverAliases(server) {
+    const aliases = new Set();
+    addAlias(aliases, server.name);
+    addAlias(aliases, server.name.split("/").pop());
+    addAlias(aliases, server.title);
+    addAlias(aliases, server.repositoryUrl?.split("/").filter(Boolean).pop());
+    for (const pkg of server.raw.packages ?? []) {
+        addAlias(aliases, pkg.identifier);
+        addAlias(aliases, pkg.identifier.split("/").pop());
+    }
+    return aliases;
+}
+function addAlias(aliases, value) {
+    const normalized = normalizeName(value);
+    if (!normalized)
+        return;
+    aliases.add(normalized);
+    for (const prefix of ["server-", "mcp-", "mcp-server-", "@modelcontextprotocol/server-"]) {
+        if (normalized.startsWith(prefix))
+            aliases.add(normalized.slice(prefix.length));
+    }
+}
+function normalizeName(value) {
+    return (value ?? "")
+        .toLowerCase()
+        .replace(/^@/, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function issueMatchesInstalled(issue, serverName, client, scope) {
+    return issue.serverName === serverName && issue.client === client && (!issue.scope || issue.scope === scope);
+}

package/dist/integrity.js

@@ -0,0 +1,14 @@
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/i;
+const OCI_SHA256_DIGEST_PATTERN = /@sha256:([a-f0-9]{64})$/i;
+export function ociDigestPin(identifier) {
+    return OCI_SHA256_DIGEST_PATTERN.exec(identifier)?.[1];
+}
+export function hasValidOciDigestPin(identifier) {
+    return ociDigestPin(identifier) !== undefined;
+}
+export function hasOciDigestMarker(identifier) {
+    return identifier.includes("@sha256:");
+}
+export function isValidSha256Hex(value) {
+    return typeof value === "string" && SHA256_HEX_PATTERN.test(value);
+}

package/dist/inventory.js

@@ -0,0 +1,169 @@
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { clientsForScope, clientConfigRootKey } from "./config.js";
+import { resolveConfigTarget } from "./install.js";
+export async function listInstalledServers(options = {}) {
+    const scope = options.scope ?? "all";
+    const client = options.client ?? "all";
+    const entries = [];
+    const issues = [];
+    let checked = 0;
+    for (const targetScope of scopesToList(scope)) {
+        const clients = client === "all" ? clientsForScope(targetScope) : [client];
+        for (const targetClient of clients) {
+            let target;
+            try {
+                target = resolveConfigTarget(targetClient, targetScope);
+            }
+            catch (error) {
+                issues.push({
+                    client: targetClient,
+                    scope: targetScope,
+                    kind: "invalid_scope",
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                continue;
+            }
+            checked += 1;
+            const names = await readInstalledServerNames(target.file, targetClient);
+            if (names.kind === "unreadable") {
+                issues.push({
+                    client: targetClient,
+                    scope: targetScope,
+                    file: target.file,
+                    kind: "unreadable",
+                    message: names.message,
+                });
+                continue;
+            }
+            for (const serverName of names.serverNames) {
+                entries.push({ client: targetClient, scope: targetScope, file: target.file, serverName });
+            }
+        }
+    }
+    entries.sort((left, right) => left.scope.localeCompare(right.scope)
+        || left.client.localeCompare(right.client)
+        || left.serverName.localeCompare(right.serverName)
+        || left.file.localeCompare(right.file));
+    return {
+        ok: issues.length === 0,
+        checked,
+        entries,
+        issues,
+    };
+}
+async function readInstalledServerNames(file, client) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { kind: "ok", serverNames: [] };
+        return { kind: "unreadable", message: error instanceof Error ? error.message : String(error) };
+    }
+    try {
+        if (client === "codex")
+            return { kind: "ok", serverNames: listCodexServerNames(raw) };
+        if (client === "continue")
+            return { kind: "ok", serverNames: listContinueServerNames(raw) };
+        const parsed = parseClientJsonConfig(raw, client);
+        const section = asRecord(parsed)[clientConfigRootKey(client)];
+        return { kind: "ok", serverNames: Object.keys(asRecord(section)).sort() };
+    }
+    catch (error) {
+        return {
+            kind: "unreadable",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function parseClientJsonConfig(raw, client) {
+    if (!raw.trim()) {
+        throw new Error(`${client} MCP config is empty; expected JSON with a "${clientConfigRootKey(client)}" object.`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`${client} MCP config is invalid JSON; expected a JSON object with "${clientConfigRootKey(client)}". Parser detail: ${detail}`);
+    }
+}
+function listCodexServerNames(raw) {
+    const names = new Set();
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+            continue;
+        const path = parseTomlPath(trimmed.slice(1, -1).trim());
+        if (path[0] === "mcp_servers" && path[1])
+            names.add(path[1]);
+    }
+    return [...names].sort();
+}
+function listContinueServerNames(raw) {
+    if (!raw.trim())
+        return [];
+    const parsed = parseYaml(raw);
+    const servers = asRecord(parsed).mcpServers;
+    if (!Array.isArray(servers))
+        return [];
+    return servers
+        .map((server) => asRecord(server).name)
+        .filter((name) => typeof name === "string" && name.length > 0)
+        .sort();
+}
+function scopesToList(scope) {
+    return scope === "all" ? ["project", "global"] : [scope];
+}
+function parseTomlPath(value) {
+    const keys = [];
+    let current = "";
+    let quoted = false;
+    let escaped = false;
+    for (const char of value) {
+        if (quoted) {
+            current += char;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === "\\") {
+                escaped = true;
+            }
+            else if (char === '"') {
+                quoted = false;
+            }
+            continue;
+        }
+        if (char === ".") {
+            keys.push(parseTomlKey(current.trim()) ?? current.trim());
+            current = "";
+        }
+        else {
+            current += char;
+            if (char === '"')
+                quoted = true;
+        }
+    }
+    if (current.trim())
+        keys.push(parseTomlKey(current.trim()) ?? current.trim());
+    return keys;
+}
+function parseTomlKey(value) {
+    if (!value)
+        return undefined;
+    if (value.startsWith('"') && value.endsWith('"')) {
+        try {
+            const parsed = JSON.parse(value);
+            return typeof parsed === "string" ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return value;
+}
+function asRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value) ? value : {};
+}