@wolpertingerlabs/drawlatch 1.0.0-alpha.1

package/dist/shared/config.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Configuration schema and loading for MCP proxy and remote server.
+ *
+ * Config files:
+ *   - proxy.config.json  — MCP proxy (local) settings
+ *   - remote.config.json — Remote server settings
+ *
+ * Each loader falls back to a legacy combined config.json (if present)
+ * for backward compatibility, then to built-in defaults.
+ *
+ * Keys directory: ~/.drawlatch/keys/
+ */
+import type { IngestorConfig } from '../remote/ingestors/types.js';
+/** Resolve the base config directory at call time (not import time).
+ *  Defaults to ~/.drawlatch in the user's home directory.
+ *  Override with MCP_CONFIG_DIR env var for custom deployments.
+ *
+ *  These are functions (not constants) so that process.env.MCP_CONFIG_DIR can
+ *  be set at runtime before the first call — important for hosts like
+ *  callboard that configure the path after ESM imports are resolved. */
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export declare function getProxyConfigPath(): string;
+export declare function getRemoteConfigPath(): string;
+export declare function getKeysDir(): string;
+export declare function getLocalKeysDir(): string;
+export declare function getRemoteKeysDir(): string;
+export declare function getPeerKeysDir(): string;
+/** MCP proxy (local) configuration */
+export interface ProxyConfig {
+    /** Remote server URL */
+    remoteUrl: string;
+    /** Key alias — resolved to keys/local/<alias>/.
+     *  Overridden by the MCP_KEY_ALIAS env var at runtime.
+     *  When set, takes precedence over localKeysDir. */
+    localKeyAlias?: string;
+    /** Path to our own key bundle (full-path override; ignored when alias is set) */
+    localKeysDir: string;
+    /** Path to the remote server's public keys */
+    remotePublicKeysDir: string;
+    /** Connection timeout (ms) */
+    connectTimeout: number;
+    /** Request timeout (ms) */
+    requestTimeout: number;
+}
+/** A single route / connector definition — scopes secrets and headers to a set of endpoints */
+export interface Route {
+    /** Alias for referencing this connector from caller connection lists.
+     *  Required for custom connectors that callers need to reference by name. */
+    alias?: string;
+    /** Human-readable name for this route (e.g., "GitHub API", "Stripe Payments").
+     *  Optional but recommended for discoverability by the local agent. */
+    name?: string;
+    /** Short description of what this route provides or what it's used for.
+     *  Optional — helps the agent understand the route's purpose. */
+    description?: string;
+    /** URL linking to API documentation for the service behind this route.
+     *  Optional — helps the agent find usage instructions. */
+    docsUrl?: string;
+    /** URL to an OpenAPI / Swagger spec (JSON or YAML) for this route's API.
+     *  Optional — provides more structured, agent-friendly documentation. */
+    openApiUrl?: string;
+    /** Headers to inject automatically into outgoing requests for this route.
+     *  These MUST NOT conflict with client-provided headers (request is rejected on conflict).
+     *  Values may contain ${VAR} placeholders resolved against this route's secrets. */
+    headers?: Record<string, string>;
+    /** Secrets available for ${VAR} placeholder resolution in this route only.
+     *  Values can be literals or "${ENV_VAR}" references resolved at startup. */
+    secrets?: Record<string, string>;
+    /** Allowlisted URL patterns (glob). A request must match at least one pattern
+     *  in this route's list to use this route. Empty = matches nothing. */
+    allowedEndpoints: string[];
+    /** Whether to resolve ${VAR} placeholders in request bodies.
+     *  Defaults to false — prevents agents from exfiltrating secrets by
+     *  writing placeholder strings into API resources and reading them back. */
+    resolveSecretsInBody?: boolean;
+    /** Optional ingestor configuration for real-time event ingestion.
+     *  When present, the remote server can start a long-lived ingestor
+     *  (WebSocket, webhook listener, or poller) for this connection. */
+    ingestor?: IngestorConfig;
+}
+/** A route after secret/header resolution — used at runtime */
+export interface ResolvedRoute {
+    /** Human-readable name for this route (carried from config) */
+    name?: string;
+    /** Short description of this route's purpose (carried from config) */
+    description?: string;
+    /** Link to API documentation for the service behind this route (carried from config) */
+    docsUrl?: string;
+    /** URL to an OpenAPI / Swagger spec for this route's API (carried from config) */
+    openApiUrl?: string;
+    headers: Record<string, string>;
+    secrets: Record<string, string>;
+    allowedEndpoints: string[];
+    /** Whether to resolve ${VAR} placeholders in request bodies (default: false) */
+    resolveSecretsInBody: boolean;
+}
+/** Per-connection ingestor overrides (all fields optional — omitted fields inherit from template). */
+export interface IngestorOverrides {
+    /** Override the Discord Gateway intents bitmask. */
+    intents?: number;
+    /** Override event type filter (e.g., ["MESSAGE_CREATE"]). Empty array = capture all. */
+    eventFilter?: string[];
+    /** Only buffer events from these guild IDs. Omitted = all guilds. */
+    guildIds?: string[];
+    /** Only buffer events from these channel IDs. Omitted = all channels. */
+    channelIds?: string[];
+    /** Only buffer events from these user IDs. Omitted = all users. */
+    userIds?: string[];
+    /** Override ring buffer capacity. */
+    bufferSize?: number;
+    /** Disable the ingestor for this connection entirely. */
+    disabled?: boolean;
+    /** Override the poll interval in milliseconds (poll ingestors only). */
+    intervalMs?: number;
+}
+/** Per-caller access configuration */
+export interface CallerConfig {
+    /** Human-readable name for this caller (used in audit logs) */
+    name?: string;
+    /** Path to this caller's public key files (signing.pub.pem + exchange.pub.pem) */
+    peerKeyDir: string;
+    /** List of connection aliases — references built-in templates (e.g., "github")
+     *  or custom connector aliases defined in the top-level connectors array. */
+    connections: string[];
+    /** Per-caller environment variable overrides.
+     *  Keys = env var names that connectors reference (e.g., "GITHUB_TOKEN").
+     *  Values = "${REAL_ENV_VAR}" (redirect to a different env var) or a literal string (direct injection).
+     *  These are resolved first, then checked BEFORE process.env during secret resolution. */
+    env?: Record<string, string>;
+    /** Per-connection ingestor overrides. Keys are connection aliases (e.g., "discord-bot").
+     *  Allows callers to customize intents, event filters, guild/channel/user ID filters,
+     *  buffer size, or disable an ingestor without modifying the connection template. */
+    ingestorOverrides?: Record<string, IngestorOverrides>;
+}
+/** Remote server configuration */
+export interface RemoteServerConfig {
+    /** Host to bind to */
+    host: string;
+    /** Port to listen on */
+    port: number;
+    /** Path to our own key bundle */
+    localKeysDir: string;
+    /** Custom connector definitions — a reusable pool referenced by alias from callers.
+     *  Each connector scopes secrets and headers to endpoint patterns. */
+    connectors?: Route[];
+    /** Per-caller access control. Keys are caller aliases (used in audit logs).
+     *  Each caller specifies their peer key directory and which connections they can use. */
+    callers: Record<string, CallerConfig>;
+    /** Rate limit: max requests per minute per session */
+    rateLimitPerMinute: number;
+}
+/**
+ * Load the MCP proxy (local) config.
+ *
+ * Resolution order:
+ *   1. proxy.config.json (flat ProxyConfig)
+ *   2. config.json → .proxy section (legacy combined format)
+ *   3. Built-in defaults
+ *
+ * Key alias resolution (applied after loading):
+ *   1. MCP_KEY_ALIAS env var (highest — set per agent at spawn time)
+ *   2. localKeyAlias in config file
+ *   3. localKeysDir in config file (explicit full path)
+ *   4. Default: keys/local/default
+ */
+export declare function loadProxyConfig(): ProxyConfig;
+/**
+ * Load the remote server config.
+ *
+ * Resolution order:
+ *   1. remote.config.json (flat RemoteServerConfig)
+ *   2. config.json → .remote section (legacy combined format)
+ *   3. Built-in defaults
+ *
+ * Legacy configs with `routes`/`authorizedPeersDir`/`connections` are auto-migrated
+ * to the caller-centric format with a deprecation warning.
+ */
+export declare function loadRemoteConfig(): RemoteServerConfig;
+export declare function saveProxyConfig(config: ProxyConfig): void;
+export declare function saveRemoteConfig(config: RemoteServerConfig): void;
+/**
+ * Resolve the effective routes for a specific caller.
+ *
+ * For each connection name in the caller's `connections` list:
+ *   1. Check custom connectors (by alias) first
+ *   2. Fall back to built-in connection templates (e.g., "github", "stripe")
+ *
+ * Returns an array of Route objects ready for `resolveRoutes()`.
+ */
+export declare function resolveCallerRoutes(config: RemoteServerConfig, callerAlias: string): Route[];
+/**
+ * Replace ${VAR} placeholders in a string with values from a secrets map.
+ * Unknown placeholders are left unchanged (with a warning).
+ */
+export declare function resolvePlaceholders(str: string, secretsMap: Record<string, string>): string;
+/**
+ * Load secrets from the config's secrets map, resolving from environment
+ * variables. Value can be a literal string or "${VAR_NAME}" to read from env.
+ *
+ * When `envOverrides` is provided (pre-resolved caller env map), those values
+ * are checked BEFORE process.env, allowing per-caller secret redirection.
+ */
+export declare function resolveSecrets(secretsMap: Record<string, string>, envOverrides?: Record<string, string>): Record<string, string>;
+/**
+ * Resolve all routes: resolve secrets from env vars, then resolve header
+ * placeholders against each route's own resolved secrets.
+ *
+ * When `envOverrides` is provided, those pre-resolved values are checked
+ * before process.env during secret resolution (used for per-caller env).
+ */
+export declare function resolveRoutes(routes: Route[], envOverrides?: Record<string, string>): ResolvedRoute[];
+//# sourceMappingURL=config.d.ts.map

package/dist/shared/config.js

@@ -0,0 +1,269 @@
+/**
+ * Configuration schema and loading for MCP proxy and remote server.
+ *
+ * Config files:
+ *   - proxy.config.json  — MCP proxy (local) settings
+ *   - remote.config.json — Remote server settings
+ *
+ * Each loader falls back to a legacy combined config.json (if present)
+ * for backward compatibility, then to built-in defaults.
+ *
+ * Keys directory: ~/.drawlatch/keys/
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadConnection } from './connections.js';
+/** Resolve the base config directory at call time (not import time).
+ *  Defaults to ~/.drawlatch in the user's home directory.
+ *  Override with MCP_CONFIG_DIR env var for custom deployments.
+ *
+ *  These are functions (not constants) so that process.env.MCP_CONFIG_DIR can
+ *  be set at runtime before the first call — important for hosts like
+ *  callboard that configure the path after ESM imports are resolved. */
+export function getConfigDir() {
+    return process.env.MCP_CONFIG_DIR ?? path.join(os.homedir(), '.drawlatch');
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), 'config.json');
+}
+export function getProxyConfigPath() {
+    return path.join(getConfigDir(), 'proxy.config.json');
+}
+export function getRemoteConfigPath() {
+    return path.join(getConfigDir(), 'remote.config.json');
+}
+export function getKeysDir() {
+    return path.join(getConfigDir(), 'keys');
+}
+export function getLocalKeysDir() {
+    return path.join(getKeysDir(), 'local');
+}
+export function getRemoteKeysDir() {
+    return path.join(getKeysDir(), 'remote');
+}
+export function getPeerKeysDir() {
+    return path.join(getKeysDir(), 'peers');
+}
+// ── Defaults ─────────────────────────────────────────────────────────────────
+function proxyDefaults() {
+    return {
+        remoteUrl: 'http://localhost:9999',
+        localKeysDir: path.join(getLocalKeysDir(), 'default'),
+        remotePublicKeysDir: path.join(getPeerKeysDir(), 'remote-server'),
+        connectTimeout: 10_000,
+        requestTimeout: 30_000,
+    };
+}
+function remoteDefaults() {
+    return {
+        host: '127.0.0.1',
+        port: 9999,
+        localKeysDir: getRemoteKeysDir(),
+        callers: {},
+        rateLimitPerMinute: 60,
+    };
+}
+// ── Split config loading (preferred) ─────────────────────────────────────────
+/**
+ * Load the MCP proxy (local) config.
+ *
+ * Resolution order:
+ *   1. proxy.config.json (flat ProxyConfig)
+ *   2. config.json → .proxy section (legacy combined format)
+ *   3. Built-in defaults
+ *
+ * Key alias resolution (applied after loading):
+ *   1. MCP_KEY_ALIAS env var (highest — set per agent at spawn time)
+ *   2. localKeyAlias in config file
+ *   3. localKeysDir in config file (explicit full path)
+ *   4. Default: keys/local/default
+ */
+export function loadProxyConfig() {
+    const def = proxyDefaults();
+    let config;
+    // Try dedicated proxy config file first
+    if (fs.existsSync(getProxyConfigPath())) {
+        const raw = JSON.parse(fs.readFileSync(getProxyConfigPath(), 'utf-8'));
+        config = { ...def, ...raw };
+    }
+    else if (fs.existsSync(getConfigPath())) {
+        // Fall back to combined config.json
+        const raw = JSON.parse(fs.readFileSync(getConfigPath(), 'utf-8'));
+        config = raw.proxy ? { ...def, ...raw.proxy } : def;
+    }
+    else {
+        config = def;
+    }
+    // Alias resolution: env var > config alias > localKeysDir > default
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentionally coerces empty string to undefined
+    const envAlias = process.env.MCP_KEY_ALIAS?.trim() || undefined;
+    const alias = envAlias ?? config.localKeyAlias;
+    if (alias) {
+        config.localKeysDir = path.join(getLocalKeysDir(), alias);
+    }
+    return config;
+}
+/**
+ * Load the remote server config.
+ *
+ * Resolution order:
+ *   1. remote.config.json (flat RemoteServerConfig)
+ *   2. config.json → .remote section (legacy combined format)
+ *   3. Built-in defaults
+ *
+ * Legacy configs with `routes`/`authorizedPeersDir`/`connections` are auto-migrated
+ * to the caller-centric format with a deprecation warning.
+ */
+export function loadRemoteConfig() {
+    const def = remoteDefaults();
+    let config;
+    // Try dedicated remote config file first
+    if (fs.existsSync(getRemoteConfigPath())) {
+        const raw = JSON.parse(fs.readFileSync(getRemoteConfigPath(), 'utf-8'));
+        config = { ...def, ...raw };
+    }
+    else if (fs.existsSync(getConfigPath())) {
+        // Fall back to combined config.json
+        const raw = JSON.parse(fs.readFileSync(getConfigPath(), 'utf-8'));
+        config = raw.remote ? { ...def, ...raw.remote } : def;
+    }
+    else {
+        config = def;
+    }
+    // Legacy migration: old format had routes/authorizedPeersDir/connections at top level
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- reading unknown legacy config shape
+    const rawConfig = config;
+    if (rawConfig.routes && !('default' in config.callers) && !rawConfig.connectors) {
+        console.error('[config] Warning: legacy config format detected (routes/authorizedPeersDir/connections). ' +
+            'Migrating to caller-centric format. Please update your remote.config.json.');
+        const legacyRoutes = rawConfig.routes;
+        const legacyConnections = rawConfig.connections ?? [];
+        const legacyPeersDir = rawConfig.authorizedPeersDir ?? path.join(getPeerKeysDir(), 'authorized-clients');
+        // Auto-assign aliases to unnamed routes for the default caller
+        const connectors = legacyRoutes.map((r, i) => ({
+            ...r,
+            alias: r.alias ?? r.name?.toLowerCase().replace(/\s+/g, '-') ?? `route-${i}`,
+        }));
+        const allConnectionNames = [...legacyConnections, ...connectors.map((c) => c.alias)];
+        config = {
+            ...def,
+            host: config.host,
+            port: config.port,
+            localKeysDir: config.localKeysDir,
+            connectors,
+            callers: {
+                default: {
+                    peerKeyDir: legacyPeersDir,
+                    connections: allConnectionNames,
+                },
+            },
+            rateLimitPerMinute: config.rateLimitPerMinute,
+        };
+    }
+    return config;
+}
+// ── Split config saving ─────────────────────────────────────────────────────
+export function saveProxyConfig(config) {
+    fs.mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(getProxyConfigPath(), JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+export function saveRemoteConfig(config) {
+    fs.mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(getRemoteConfigPath(), JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+// ── Per-caller route resolution ──────────────────────────────────────────
+/**
+ * Resolve the effective routes for a specific caller.
+ *
+ * For each connection name in the caller's `connections` list:
+ *   1. Check custom connectors (by alias) first
+ *   2. Fall back to built-in connection templates (e.g., "github", "stripe")
+ *
+ * Returns an array of Route objects ready for `resolveRoutes()`.
+ */
+export function resolveCallerRoutes(config, callerAlias) {
+    if (!(callerAlias in config.callers))
+        return [];
+    const caller = config.callers[callerAlias];
+    // Build lookup map for custom connectors by alias
+    const connectorsByAlias = new Map();
+    for (const c of config.connectors ?? []) {
+        if (c.alias)
+            connectorsByAlias.set(c.alias, c);
+    }
+    return caller.connections.map((name) => {
+        // Custom connectors take precedence over built-in templates
+        const custom = connectorsByAlias.get(name);
+        if (custom)
+            return custom;
+        return loadConnection(name);
+    });
+}
+// ── Secret / placeholder resolution ──────────────────────────────────────────
+/**
+ * Replace ${VAR} placeholders in a string with values from a secrets map.
+ * Unknown placeholders are left unchanged (with a warning).
+ */
+export function resolvePlaceholders(str, secretsMap) {
+    return str.replace(/\$\{(\w+)\}/g, (match, name) => {
+        if (name in secretsMap)
+            return secretsMap[name];
+        console.error(`[config] Warning: placeholder ${match} not found in secrets`);
+        return match;
+    });
+}
+/**
+ * Load secrets from the config's secrets map, resolving from environment
+ * variables. Value can be a literal string or "${VAR_NAME}" to read from env.
+ *
+ * When `envOverrides` is provided (pre-resolved caller env map), those values
+ * are checked BEFORE process.env, allowing per-caller secret redirection.
+ */
+export function resolveSecrets(secretsMap, envOverrides) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(secretsMap)) {
+        const envMatch = /^\$\{(.+)\}$/.exec(value);
+        if (envMatch) {
+            const varName = envMatch[1];
+            const envVal = envOverrides?.[varName] ?? process.env[varName];
+            if (envVal !== undefined) {
+                resolved[key] = envVal;
+            }
+            else {
+                console.error(`[secrets] Warning: env var ${varName} not found for key ${key}`);
+            }
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+/**
+ * Resolve all routes: resolve secrets from env vars, then resolve header
+ * placeholders against each route's own resolved secrets.
+ *
+ * When `envOverrides` is provided, those pre-resolved values are checked
+ * before process.env during secret resolution (used for per-caller env).
+ */
+export function resolveRoutes(routes, envOverrides) {
+    return routes.map((route) => {
+        const resolvedSecrets = resolveSecrets(route.secrets ?? {}, envOverrides);
+        const resolvedHeaders = {};
+        for (const [key, value] of Object.entries(route.headers ?? {})) {
+            resolvedHeaders[key] = resolvePlaceholders(value, resolvedSecrets);
+        }
+        return {
+            ...(route.name !== undefined && { name: route.name }),
+            ...(route.description !== undefined && { description: route.description }),
+            ...(route.docsUrl !== undefined && { docsUrl: route.docsUrl }),
+            ...(route.openApiUrl !== undefined && { openApiUrl: route.openApiUrl }),
+            headers: resolvedHeaders,
+            secrets: resolvedSecrets,
+            allowedEndpoints: route.allowedEndpoints,
+            resolveSecretsInBody: route.resolveSecretsInBody ?? false,
+        };
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/shared/connections.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Connection template loading.
+ *
+ * Connections are pre-built Route templates (JSON files) that ship with
+ * the package in the connections/ directory. They provide ready-made
+ * configurations for popular APIs (GitHub, Stripe, Trello, etc.).
+ *
+ * At runtime, templates are loaded from disk relative to this module's
+ * location, so they work from both src/ (dev via tsx) and dist/ (production).
+ */
+import type { Route } from './config.js';
+/** Metadata about a built-in connection template — used by UIs to render
+ *  connection cards, form fields, and badges without parsing raw JSON. */
+export interface ConnectionTemplateInfo {
+    /** Template alias / filename (e.g., "github", "slack"). */
+    alias: string;
+    /** Human-readable name (e.g., "GitHub API"). */
+    name: string;
+    /** Short description of the connection's purpose. */
+    description?: string;
+    /** Link to API documentation. */
+    docsUrl?: string;
+    /** URL to an OpenAPI / Swagger spec. */
+    openApiUrl?: string;
+    /** Secret names referenced in route headers — these are auto-injected
+     *  into every request, so they must always be configured. */
+    requiredSecrets: string[];
+    /** Secret names defined in the template but NOT referenced in headers.
+     *  Used by ingestors, URL placeholders, body templates, etc. */
+    optionalSecrets: string[];
+    /** Whether this connection has an ingestor for real-time events. */
+    hasIngestor: boolean;
+    /** Ingestor type, when present. */
+    ingestorType?: 'websocket' | 'webhook' | 'poll';
+    /** Allowlisted URL patterns (glob). */
+    allowedEndpoints: string[];
+}
+/**
+ * Load a single connection template by name.
+ *
+ * @param name — Connection name (e.g., "github", "stripe", "trello").
+ *               Must match the filename without the .json extension.
+ * @returns The parsed Route object from the template.
+ * @throws If the template file does not exist or contains invalid JSON.
+ */
+export declare function loadConnection(name: string): Route;
+/**
+ * List all available connection template names.
+ *
+ * Scans the connections directory for .json files and returns their
+ * basenames (without extension), sorted alphabetically.
+ */
+export declare function listAvailableConnections(): string[];
+/**
+ * List all available connection templates with structured metadata.
+ *
+ * For each built-in template, returns its name, description, docs links,
+ * secrets (categorized as required vs. optional), ingestor info, and
+ * allowed endpoints.
+ *
+ * Secret categorization:
+ *   - **required** — referenced in route `headers` values (auto-injected
+ *     into every outgoing request, so they must always be configured).
+ *   - **optional** — defined in the template's `secrets` map but not
+ *     referenced in headers (used by ingestors, URL placeholders, etc.).
+ *
+ * Used by:
+ *   - callboard's ConnectionManager (local mode, direct import)
+ *   - admin_list_connection_templates tool handler (remote mode, Stage 3)
+ */
+export declare function listConnectionTemplates(): ConnectionTemplateInfo[];
+//# sourceMappingURL=connections.d.ts.map

package/dist/shared/connections.js

@@ -0,0 +1,103 @@
+/**
+ * Connection template loading.
+ *
+ * Connections are pre-built Route templates (JSON files) that ship with
+ * the package in the connections/ directory. They provide ready-made
+ * configurations for popular APIs (GitHub, Stripe, Trello, etc.).
+ *
+ * At runtime, templates are loaded from disk relative to this module's
+ * location, so they work from both src/ (dev via tsx) and dist/ (production).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Directory containing connection template JSON files. */
+const CONNECTIONS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'connections');
+/**
+ * Load a single connection template by name.
+ *
+ * @param name — Connection name (e.g., "github", "stripe", "trello").
+ *               Must match the filename without the .json extension.
+ * @returns The parsed Route object from the template.
+ * @throws If the template file does not exist or contains invalid JSON.
+ */
+export function loadConnection(name) {
+    const filePath = path.join(CONNECTIONS_DIR, `${name}.json`);
+    if (!fs.existsSync(filePath)) {
+        const available = listAvailableConnections();
+        throw new Error(`Unknown connection "${name}". Available connections: ${available.join(', ') || '(none)'}`);
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+}
+/**
+ * List all available connection template names.
+ *
+ * Scans the connections directory for .json files and returns their
+ * basenames (without extension), sorted alphabetically.
+ */
+export function listAvailableConnections() {
+    if (!fs.existsSync(CONNECTIONS_DIR)) {
+        return [];
+    }
+    return fs
+        .readdirSync(CONNECTIONS_DIR, 'utf-8')
+        .filter((f) => f.endsWith('.json'))
+        .map((f) => f.replace(/\.json$/, ''))
+        .sort();
+}
+// ── Template introspection ────────────────────────────────────────────────
+/** Extract ${VAR} placeholder names from a string. */
+function extractPlaceholderNames(str) {
+    const names = new Set();
+    for (const match of str.matchAll(/\$\{(\w+)\}/g)) {
+        names.add(match[1]);
+    }
+    return names;
+}
+/**
+ * List all available connection templates with structured metadata.
+ *
+ * For each built-in template, returns its name, description, docs links,
+ * secrets (categorized as required vs. optional), ingestor info, and
+ * allowed endpoints.
+ *
+ * Secret categorization:
+ *   - **required** — referenced in route `headers` values (auto-injected
+ *     into every outgoing request, so they must always be configured).
+ *   - **optional** — defined in the template's `secrets` map but not
+ *     referenced in headers (used by ingestors, URL placeholders, etc.).
+ *
+ * Used by:
+ *   - callboard's ConnectionManager (local mode, direct import)
+ *   - admin_list_connection_templates tool handler (remote mode, Stage 3)
+ */
+export function listConnectionTemplates() {
+    return listAvailableConnections().map((alias) => {
+        const route = loadConnection(alias);
+        // Collect secret names referenced in header values
+        const headerSecretNames = new Set();
+        for (const value of Object.values(route.headers ?? {})) {
+            for (const name of extractPlaceholderNames(value)) {
+                headerSecretNames.add(name);
+            }
+        }
+        // Partition secrets into required (in headers) vs optional (elsewhere)
+        const allSecretNames = Object.keys(route.secrets ?? {});
+        const requiredSecrets = allSecretNames.filter((s) => headerSecretNames.has(s));
+        const optionalSecrets = allSecretNames.filter((s) => !headerSecretNames.has(s));
+        return {
+            alias,
+            name: route.name ?? alias,
+            ...(route.description !== undefined && { description: route.description }),
+            ...(route.docsUrl !== undefined && { docsUrl: route.docsUrl }),
+            ...(route.openApiUrl !== undefined && { openApiUrl: route.openApiUrl }),
+            requiredSecrets,
+            optionalSecrets,
+            hasIngestor: route.ingestor !== undefined,
+            ...(route.ingestor !== undefined && { ingestorType: route.ingestor.type }),
+            allowedEndpoints: route.allowedEndpoints,
+        };
+    });
+}
+//# sourceMappingURL=connections.js.map