@proofofwork-agency/toolpin 0.2.3

package/dist/clientSupport.js

@@ -0,0 +1,76 @@
+export const TOOLPIN_CLIENT_SUPPORT_META = "dev.toolpin/clientSupport";
+export function clientSupportBlock(server) {
+    const value = server.raw._meta?.[TOOLPIN_CLIENT_SUPPORT_META] ?? server.registryMeta?.[TOOLPIN_CLIENT_SUPPORT_META];
+    if (!isRecord(value))
+        return undefined;
+    const defaultStatus = statusValue(value.default);
+    if (!defaultStatus)
+        return undefined;
+    const clientsValue = isRecord(value.clients) ? value.clients : {};
+    const clients = {};
+    for (const [client, entry] of Object.entries(clientsValue)) {
+        if (!isRecord(entry))
+            continue;
+        const status = statusValue(entry.status);
+        if (!status)
+            continue;
+        clients[client] = {
+            status,
+            installMode: typeof entry.installMode === "string" ? entry.installMode : undefined,
+            requirements: stringArray(entry.requirements),
+            setupCommands: stringArray(entry.setupCommands),
+            notes: typeof entry.notes === "string" ? entry.notes : undefined,
+        };
+    }
+    return { default: defaultStatus, clients };
+}
+export function clientSupportFor(server, client) {
+    const support = clientSupportBlock(server);
+    if (!support)
+        return undefined;
+    return support.clients[client] ?? { status: support.default };
+}
+export function assertToolPinInstallableForClient(server, client) {
+    const support = clientSupportFor(server, client);
+    if (!support || support.status === "toolpin-installable")
+        return;
+    throw new Error(clientSupportSkipReason(server, client, support));
+}
+export function installableClientsForServer(server, clients) {
+    const installable = [];
+    const skipped = [];
+    for (const client of clients) {
+        const support = clientSupportFor(server, client);
+        if (!support || support.status === "toolpin-installable") {
+            installable.push(client);
+            continue;
+        }
+        skipped.push({
+            client,
+            status: support.status,
+            reason: clientSupportSkipReason(server, client, support),
+        });
+    }
+    return { clients: installable, skipped };
+}
+export function clientSupportSkipReason(server, client, support = clientSupportFor(server, client)) {
+    if (!support || support.status === "toolpin-installable")
+        return `${server.name}@${server.version} is ToolPin-installable for ${client}.`;
+    if (support.status === "external-setup") {
+        const commands = support.setupCommands?.length ? ` Setup: ${support.setupCommands.join("; ")}` : "";
+        const notes = support.notes ? ` ${support.notes}` : "";
+        return `${server.name}@${server.version} supports ${client} through external setup, not ToolPin direct install.${notes}${commands}`;
+    }
+    return `${server.name}@${server.version} is not supported for ${client} by this ToolPin curated entry.`;
+}
+function statusValue(value) {
+    return value === "toolpin-installable" || value === "external-setup" || value === "unsupported" ? value : undefined;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/codexToml.js

@@ -0,0 +1,213 @@
+export function codexTomlFromClientConfig(config) {
+    const servers = codexServers(config);
+    return Object.entries(servers).map(([serverName, serverConfig]) => serverToToml(serverName, serverConfig)).join("\n\n");
+}
+export function mergeCodexToml(existing, incoming) {
+    const servers = codexServers(incoming);
+    if (Object.keys(servers).length === 0)
+        return existing;
+    let next = existing;
+    for (const serverName of Object.keys(servers)) {
+        next = removeServerTables(next, serverName).toml;
+    }
+    const prefix = next.trimEnd();
+    const fragment = codexTomlFromClientConfig(incoming);
+    return `${prefix ? `${prefix}\n\n` : ""}${fragment}\n`;
+}
+export function removeCodexServerToml(existing, serverName) {
+    const result = removeServerTables(existing, serverName);
+    if (!result.removed)
+        return existing;
+    return result.toml ? `${result.toml}\n` : "";
+}
+export function readCodexServerConfig(existing, serverName) {
+    const config = {};
+    let currentPath = [];
+    let found = false;
+    for (const rawLine of existing.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("[") && line.endsWith("]")) {
+            currentPath = parseTomlPath(line.slice(1, -1).trim());
+            if (currentPath[0] === "mcp_servers" && currentPath[1] === serverName)
+                found = true;
+            continue;
+        }
+        if (currentPath[0] !== "mcp_servers" || currentPath[1] !== serverName)
+            continue;
+        const equalIndex = line.indexOf("=");
+        if (equalIndex < 0)
+            continue;
+        const key = parseTomlKey(line.slice(0, equalIndex).trim());
+        const value = parseTomlValue(line.slice(equalIndex + 1).trim());
+        if (!key || value === undefined)
+            continue;
+        const nested = currentPath.slice(2);
+        let target = config;
+        for (const segment of nested) {
+            const existingValue = target[segment];
+            if (!isPlainObject(existingValue))
+                target[segment] = {};
+            target = target[segment];
+        }
+        target[key] = value;
+    }
+    return found ? config : undefined;
+}
+function codexServers(config) {
+    const root = asRecord(config);
+    const servers = asRecord(root.mcp_servers);
+    return Object.fromEntries(Object.entries(servers).flatMap(([serverName, value]) => {
+        const serverConfig = asRecord(value);
+        return Object.keys(serverConfig).length > 0 ? [[serverName, serverConfig]] : [];
+    }));
+}
+function serverToToml(serverName, config) {
+    const table = `mcp_servers.${tomlKey(serverName)}`;
+    const scalarLines = [];
+    const nestedTables = [];
+    for (const [key, value] of Object.entries(config)) {
+        if (value === undefined)
+            continue;
+        if (isPlainObject(value)) {
+            const entries = Object.entries(value).filter((entry) => isTomlValue(entry[1]));
+            if (entries.length > 0) {
+                nestedTables.push([`[${table}.${tomlKey(key)}]`, ...entries.map(([childKey, childValue]) => `${tomlKey(childKey)} = ${tomlValue(childValue)}`)].join("\n"));
+            }
+        }
+        else if (isTomlValue(value)) {
+            scalarLines.push(`${tomlKey(key)} = ${tomlValue(value)}`);
+        }
+    }
+    return [`[${table}]`, ...scalarLines, ...nestedTables].join("\n");
+}
+function removeServerTables(existing, serverName) {
+    // Codex's documented writer uses [mcp_servers.<name>] headers; preserve unrelated TOML forms.
+    const lines = existing.split(/\r?\n/);
+    const kept = [];
+    let skipping = false;
+    let removed = false;
+    for (const line of lines) {
+        const header = line.trim();
+        if (header.startsWith("[") && header.endsWith("]")) {
+            skipping = isServerTableHeader(header, serverName);
+            if (skipping)
+                removed = true;
+            if (!skipping)
+                kept.push(line);
+            continue;
+        }
+        if (!skipping)
+            kept.push(line);
+    }
+    return { toml: kept.join("\n").trimEnd(), removed };
+}
+function isServerTableHeader(header, serverName) {
+    const tableName = header.slice(1, -1).trim();
+    const quoted = tomlKey(serverName);
+    const keys = [quoted];
+    if (isBareKey(serverName))
+        keys.push(serverName);
+    return keys.some((key) => {
+        const prefix = `mcp_servers.${key}`;
+        return tableName === prefix || tableName.startsWith(`${prefix}.`);
+    });
+}
+function isTomlValue(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || (Array.isArray(value) && value.every((entry) => typeof entry === "string"));
+}
+function tomlValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : JSON.stringify(String(value));
+    if (typeof value === "boolean")
+        return String(value);
+    return `[${value.map((entry) => JSON.stringify(entry)).join(", ")}]`;
+}
+function tomlKey(key) {
+    return isBareKey(key) ? key : JSON.stringify(key);
+}
+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 parseTomlValue(value) {
+    if (value.startsWith('"')) {
+        try {
+            const parsed = JSON.parse(value);
+            return typeof parsed === "string" ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (value.startsWith("[") && value.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(value);
+            return Array.isArray(parsed) && parsed.every((entry) => typeof entry === "string") ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+function isBareKey(key) {
+    return /^[A-Za-z0-9_-]+$/.test(key);
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+    return isPlainObject(value) ? value : {};
+}

package/dist/config.js

@@ -0,0 +1,337 @@
+import { assertToolPinInstallableForClient } from "./clientSupport.js";
+export const ALL_CLIENTS = [
+    "claude",
+    "cursor",
+    "vscode",
+    "codex",
+    "opencode",
+    "windsurf",
+    "cline",
+    "continue",
+    "gemini",
+    "zed",
+    "roo",
+    "generic",
+];
+export const PROJECT_CLIENTS = ["claude", "cursor", "vscode", "codex", "opencode", "gemini", "roo"];
+export const GLOBAL_CLIENTS = ["cursor", "vscode", "codex", "opencode", "windsurf", "cline", "continue", "gemini"];
+export function exportClientConfig(server, client) {
+    assertToolPinInstallableForClient(server, client);
+    const notes = [];
+    const launch = selectLaunchTarget(server);
+    if (!launch) {
+        throw new Error(`No package or remote launch target found for ${server.name}@${server.version}`);
+    }
+    if (launch.kind === "remote") {
+        notes.push("Remote server selected; no local runtime install is required.");
+        return {
+            client,
+            serverName: server.name,
+            config: wrapClientConfig(client, server.name, {
+                type: launch.remote.type,
+                url: launch.remote.url,
+                headers: headersToInputs(launch.remote, client),
+            }),
+            notes,
+        };
+    }
+    const localConfig = packageToLocalConfig(launch.pkg, notes, client);
+    return {
+        client,
+        serverName: server.name,
+        config: wrapClientConfig(client, server.name, localConfig),
+        notes,
+    };
+}
+export function selectLaunchTarget(server) {
+    const remotes = server.raw.remotes ?? [];
+    const packages = server.raw.packages ?? [];
+    const streamableRemote = remotes.find((remote) => remote.type === "streamable-http");
+    if (streamableRemote)
+        return { kind: "remote", remote: streamableRemote };
+    if (remotes[0])
+        return { kind: "remote", remote: remotes[0] };
+    const preferredPackage = packages.find((pkg) => pkg.registryType === "oci") ??
+        packages.find((pkg) => pkg.registryType === "mcpb") ??
+        packages[0];
+    return preferredPackage ? { kind: "package", pkg: preferredPackage } : undefined;
+}
+function packageToLocalConfig(pkg, notes, client) {
+    const env = environmentToPlaceholders(pkg, client);
+    const explicitCommand = typeof pkg.command === "string" ? pkg.command : undefined;
+    const explicitArgs = Array.isArray(pkg.args) ? pkg.args.filter((arg) => typeof arg === "string") : undefined;
+    if (explicitCommand) {
+        notes.push(runtimeRequirementNote(pkg));
+        return { command: explicitCommand, args: explicitArgs ?? [], env };
+    }
+    switch (pkg.registryType) {
+        case "npm": {
+            const spec = pkg.version ? `${pkg.identifier}@${pkg.version}` : pkg.identifier;
+            if (pkg.runtimeHint === "bun") {
+                notes.push("Requires Bun and bunx on PATH.");
+                return { command: "bunx", args: [spec, ...packageArguments(pkg)], env };
+            }
+            notes.push("Requires Node.js and npm/npx on PATH.");
+            return { command: "npx", args: ["-y", spec, ...packageArguments(pkg)], env };
+        }
+        case "pypi": {
+            const spec = pkg.version ? `${pkg.identifier}==${pkg.version}` : pkg.identifier;
+            notes.push("Requires uv/uvx on PATH.");
+            return { command: "uvx", args: [spec], env };
+        }
+        case "nuget": {
+            const spec = pkg.version ? `${pkg.identifier}@${pkg.version}` : pkg.identifier;
+            notes.push("Requires .NET SDK dnx support on PATH.");
+            return { command: "dnx", args: [spec], env };
+        }
+        case "cargo": {
+            notes.push("Requires a prior `cargo install` and compiled binary on PATH.");
+            return { command: pkg.identifier, args: [], env };
+        }
+        case "oci": {
+            notes.push("Requires Docker-compatible runtime. Review mounts and network policy before running.");
+            return { command: "docker", args: ["run", "--rm", "-i", ...dockerEnvArgs(pkg), pkg.identifier], env };
+        }
+        case "mcpb": {
+            notes.push("MCPB bundle requires a compatible MCPB installer/runtime.");
+            return { command: "mcpb", args: ["run", pkg.identifier], env };
+        }
+        default:
+            notes.push(`Unknown registry type ${pkg.registryType}; generated a placeholder command.`);
+            return { command: pkg.identifier, args: packageArguments(pkg), env };
+    }
+}
+function packageArguments(pkg) {
+    return Array.isArray(pkg.packageArguments) ? pkg.packageArguments.filter((arg) => typeof arg === "string") : [];
+}
+function runtimeRequirementNote(pkg) {
+    if (pkg.runtimeHint === "bun")
+        return "Requires Bun on PATH.";
+    if (pkg.runtimeHint === "docker")
+        return "Requires Docker-compatible runtime. Review mounts and network policy before running.";
+    if (pkg.runtimeHint)
+        return `Requires ${pkg.runtimeHint} on PATH.`;
+    return "Uses the command declared by registry metadata; review generated arguments before running.";
+}
+function dockerEnvArgs(pkg) {
+    const names = [...new Set((pkg.environmentVariables ?? []).map((variable) => variable.name).filter(Boolean))];
+    return names.flatMap((name) => ["-e", name]);
+}
+function environmentToPlaceholders(pkg, client) {
+    const env = {};
+    for (const variable of pkg.environmentVariables ?? []) {
+        env[variable.name] = variable.default ?? placeholderFor(client, variable.name);
+    }
+    return env;
+}
+function headersToInputs(remote, client) {
+    if (!remote.headers?.length)
+        return undefined;
+    return Object.fromEntries(remote.headers.map((header) => [header.name, placeholderFor(client, header.name)]));
+}
+function wrapClientConfig(client, serverName, config) {
+    switch (client) {
+        case "vscode":
+            return { servers: { [serverName]: config } };
+        case "codex":
+            return { mcp_servers: { [serverName]: toCodexMcp(config) } };
+        case "opencode":
+            return { $schema: "https://opencode.ai/config.json", mcp: { [serverName]: toOpenCodeMcp(config) } };
+        case "windsurf":
+            return { mcpServers: { [serverName]: toWindsurfMcp(config) } };
+        case "cline":
+            return { mcpServers: { [serverName]: toClineMcp(config) } };
+        case "gemini":
+            return { mcpServers: { [serverName]: toGeminiMcp(config) } };
+        case "continue":
+            return { name: "ToolPin Config", version: "1.0.0", schema: "v1", mcpServers: [toContinueMcp(serverName, config)] };
+        case "zed":
+            return { context_servers: { [serverName]: toZedMcp(config) } };
+        case "roo":
+            return { mcpServers: { [serverName]: toRooMcp(config) } };
+        case "claude":
+        case "cursor":
+        case "generic":
+        default:
+            return { mcpServers: { [serverName]: config } };
+    }
+}
+export function clientConfigRootKey(client) {
+    switch (client) {
+        case "opencode":
+            return "mcp";
+        case "vscode":
+            return "servers";
+        case "codex":
+            return "mcp_servers";
+        case "zed":
+            return "context_servers";
+        case "claude":
+        case "cursor":
+        case "windsurf":
+        case "cline":
+        case "gemini":
+        case "continue":
+        case "roo":
+        case "generic":
+        default:
+            return "mcpServers";
+    }
+}
+export function clientsForScope(scope) {
+    return scope === "project" ? PROJECT_CLIENTS : GLOBAL_CLIENTS;
+}
+export function isClientName(value) {
+    return ALL_CLIENTS.includes(String(value));
+}
+function toCodexMcp(config) {
+    if (typeof config.url === "string") {
+        const headers = config.headers;
+        return {
+            url: config.url,
+            ...(headers && typeof headers === "object" && !Array.isArray(headers) ? { http_headers: headers } : {}),
+        };
+    }
+    return {
+        command: config.command,
+        args: config.args,
+        env: config.env,
+    };
+}
+function toOpenCodeMcp(config) {
+    if (typeof config.url === "string") {
+        return {
+            type: "remote",
+            url: config.url,
+            enabled: true,
+            headers: config.headers,
+        };
+    }
+    const command = typeof config.command === "string" ? config.command : undefined;
+    const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
+    return {
+        type: "local",
+        command: command ? [command, ...args] : args,
+        enabled: true,
+        environment: config.env,
+    };
+}
+function toWindsurfMcp(config) {
+    if (typeof config.url === "string") {
+        return omitUndefined({
+            serverUrl: config.url,
+            headers: config.headers,
+        });
+    }
+    return omitUndefined({
+        command: config.command,
+        args: config.args,
+        env: config.env,
+    });
+}
+function toClineMcp(config) {
+    if (typeof config.url === "string") {
+        return omitUndefined({
+            type: config.type === "streamable-http" ? "streamableHttp" : config.type,
+            url: config.url,
+            headers: config.headers,
+            disabled: false,
+            autoApprove: [],
+        });
+    }
+    return omitUndefined({
+        command: config.command,
+        args: config.args,
+        env: config.env,
+        disabled: false,
+        autoApprove: [],
+    });
+}
+function toGeminiMcp(config) {
+    if (typeof config.url === "string") {
+        return omitUndefined({
+            ...(config.type === "streamable-http" ? { httpUrl: config.url } : { url: config.url }),
+            headers: config.headers,
+        });
+    }
+    return omitUndefined({
+        command: config.command,
+        args: config.args,
+        env: config.env,
+    });
+}
+function toContinueMcp(serverName, config) {
+    if (typeof config.url === "string") {
+        return omitUndefined({
+            name: serverName,
+            type: config.type,
+            url: config.url,
+            requestOptions: headersRequestOptions(config.headers),
+        });
+    }
+    return omitUndefined({
+        name: serverName,
+        command: config.command,
+        args: config.args,
+        env: config.env,
+    });
+}
+function toZedMcp(config) {
+    if (typeof config.url === "string") {
+        return omitUndefined({
+            url: config.url,
+            headers: config.headers,
+        });
+    }
+    return omitUndefined({
+        command: config.command,
+        args: config.args,
+        env: config.env,
+    });
+}
+function toRooMcp(config) {
+    if (typeof config.url === "string") {
+        return omitUndefined({
+            type: config.type,
+            url: config.url,
+            headers: config.headers,
+            disabled: false,
+        });
+    }
+    return omitUndefined({
+        command: config.command,
+        args: config.args,
+        env: config.env,
+        disabled: false,
+    });
+}
+function placeholderFor(client, name) {
+    switch (client) {
+        case "windsurf":
+            return `\${env:${name}}`;
+        case "gemini":
+            return `\${${name}}`;
+        case "continue":
+            return `\${{ secrets.${name} }}`;
+        case "roo":
+            return `<${name}>`;
+        case "cline":
+        case "zed":
+        case "claude":
+        case "cursor":
+        case "vscode":
+        case "codex":
+        case "opencode":
+        case "generic":
+        default:
+            return `<${name}>`;
+    }
+}
+function omitUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== undefined));
+}
+function headersRequestOptions(headers) {
+    if (!headers || typeof headers !== "object" || Array.isArray(headers) || Object.keys(headers).length === 0)
+        return undefined;
+    return { headers };
+}

package/dist/constants.js

@@ -0,0 +1,3 @@
+export const DEFAULT_LOCKFILE_PATH = "mcp-lock.json";
+export const DEFAULT_SIGNATURE_PATH = "mcp-lock.sig";
+export const DEFAULT_POLICY_PATH = ".toolpin/policy.json";