skillscript-runtime 0.3.4 → 0.4.1

package/dist/connectors/config.js

@@ -0,0 +1,276 @@
+// v0.4.0 — `connectors.json` loader. Reads + validates the per-host
+// connector configuration file at runtime startup and wires the
+// declared instances into the Registry.
+//
+// Spec: ERD §3 + Perry's v0.4.0 kickoff (b3f6c5ed) + amendment (58a9d3d3).
+//
+// Surface shape (matches Claude Desktop's `mcp.json` convention so authors
+// don't carry two mental models):
+//
+//   {
+//     "youtrack": {
+//       "class": "RemoteMcpConnector",
+//       "config": {
+//         "command": "npx",
+//         "args": ["mcp-remote", "https://...", "--header", "Authorization:${AUTH_HEADER}"],
+//         "env": { "AUTH_HEADER": "Bearer ${YOUTRACK_TOKEN}" }
+//       }
+//     }
+//   }
+//
+// **Credential discipline (v0.4.0 hard requirement, Perry's amendment):**
+// `connectors.json` is secret-bearing. Default `.gitignore` excludes it;
+// `connectors.json.example` ships at repo root as the template. See README.
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, basename, resolve } from "node:path";
+import { CallbackMcpConnector } from "./mcp.js";
+import { RemoteMcpConnector } from "./mcp-remote.js";
+export const KNOWN_CONNECTOR_CLASSES = new Map([
+    ["CallbackMcpConnector", { ctor: CallbackMcpConnector }],
+    [
+        "RemoteMcpConnector",
+        {
+            ctor: RemoteMcpConnector,
+            fromConfig: (config) => RemoteMcpConnector.fromConfig(config),
+        },
+    ],
+]);
+/** Listable for error messages + runtime_capabilities discovery. */
+export function listKnownConnectorClasses() {
+    return [...KNOWN_CONNECTOR_CLASSES.keys()];
+}
+/**
+ * v0.4.1 — credential-discipline backstop. Walk up from `connectors.json`'s
+ * dir looking for `.git/`. If found, check whether any `.gitignore` between
+ * the file and the git root excludes `connectors.json`. Returns a warning
+ * string when the file appears to be in a git repo BUT not gitignored.
+ * `null` means either (a) not in a git repo, or (b) gitignored cleanly.
+ *
+ * Heuristic — not a full gitignore parser. Recognizes the canonical
+ * exclusion patterns: `connectors.json`, `/connectors.json`, `*.json`
+ * (broad), and anchored ancestor-dir matches. False negatives (warning
+ * fires on a gitignored file) are possible with exotic gitignore shapes;
+ * those are operator-fixable. False positives (warning suppressed on a
+ * tracked file) are the worse outcome and the heuristic biases against.
+ */
+export function detectGitignoreRisk(configPath) {
+    let dir = dirname(resolve(configPath));
+    const filename = basename(configPath);
+    const gitignorePaths = [];
+    let gitRoot = null;
+    // Walk up looking for .git/ and collecting any .gitignore files along the way.
+    while (true) {
+        if (existsSync(`${dir}/.git`)) {
+            gitRoot = dir;
+            const rootGitignore = `${dir}/.gitignore`;
+            if (existsSync(rootGitignore))
+                gitignorePaths.push(rootGitignore);
+            break;
+        }
+        const localGitignore = `${dir}/.gitignore`;
+        if (existsSync(localGitignore))
+            gitignorePaths.push(localGitignore);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // hit filesystem root
+        dir = parent;
+    }
+    if (gitRoot === null)
+        return null; // not in a git repo
+    // Scan all collected .gitignore files for any line that would exclude
+    // the connectors.json filename. Patterns recognized: bare name, anchored
+    // `/<name>`, anchored to subdir, or wildcard `*.json` (rare but valid).
+    const patterns = [filename, `/${filename}`];
+    for (const giPath of gitignorePaths) {
+        let raw;
+        try {
+            raw = readFileSync(giPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lines = raw.split("\n").map((l) => l.trim()).filter((l) => l !== "" && !l.startsWith("#"));
+        for (const line of lines) {
+            if (patterns.includes(line))
+                return null; // explicitly ignored
+            // Wildcard match: `*.json` or `*` — broad, assume covers the file.
+            if (line === "*" || line === "*.json")
+                return null;
+        }
+    }
+    // In a git repo, but no .gitignore entry seems to cover connectors.json.
+    // Warn (informational; not blocking).
+    return `connectors.json appears to be in a git-tracked directory (${gitRoot}) without a .gitignore entry. Credentials in this file may end up committed. Add '/connectors.json' to your .gitignore — or use the bundled \`connectors.json.example\` template + \${ENV} substitution pattern instead.`;
+}
+/**
+ * Resolve `${NAME}` patterns in a string against the provided env.
+ * Missing var → throws (clear error rather than silent empty string).
+ * Used by the loader on every string value in the `config` block.
+ */
+export function resolveEnvSubstitution(value, env) {
+    return value.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_match, name) => {
+        const v = env[name];
+        if (v === undefined) {
+            throw new Error(`Environment variable '\${${name}}' referenced in connectors.json is not set.`);
+        }
+        return v;
+    });
+}
+/** Walk a config tree and resolve `${NAME}` substitutions on every string leaf. */
+function resolveConfigEnv(value, env) {
+    if (typeof value === "string")
+        return resolveEnvSubstitution(value, env);
+    if (Array.isArray(value))
+        return value.map((v) => resolveConfigEnv(v, env));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = resolveConfigEnv(v, env);
+        return out;
+    }
+    return value;
+}
+/**
+ * Read + parse `connectors.json` at the given path. Validate the top-
+ * level shape. Resolve `${VAR}` substitutions. Instantiate each entry
+ * via the closed-set class registry's `fromConfig` factory (when
+ * present; entries pointing at classes without one get a clear error
+ * and a `null` instance, surfaced via `errors`).
+ *
+ * Missing file → returns `{connectors: [], errors: []}` (graceful: not
+ * every deployment uses external connectors). Malformed JSON or
+ * structural errors → returned in `errors[]` for the bootstrap caller
+ * to log and refuse to start, or for the lint surface to consume.
+ */
+export function loadConnectorsConfig(opts) {
+    const env = opts.env ?? process.env;
+    let raw;
+    try {
+        raw = readFileSync(opts.path, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { connectors: [], errors: [] };
+        return { connectors: [], errors: [`connectors.json: failed to read '${opts.path}': ${err.message}`] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { connectors: [], errors: [`connectors.json: malformed JSON in '${opts.path}': ${err.message}`] };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { connectors: [], errors: [`connectors.json: top-level must be an object mapping connector names to {class, config}. Got: ${Array.isArray(parsed) ? "array" : typeof parsed}.`] };
+    }
+    const connectors = [];
+    const errors = [];
+    for (const [name, entry] of Object.entries(parsed)) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            errors.push(`connectors.json: entry '${name}' must be an object with {class, config}. Got: ${Array.isArray(entry) ? "array" : entry === null ? "null" : typeof entry}.`);
+            continue;
+        }
+        const obj = entry;
+        const className = obj["class"];
+        if (typeof className !== "string" || className === "") {
+            errors.push(`connectors.json: entry '${name}' is missing required string field 'class'.`);
+            continue;
+        }
+        const rawConfig = obj["config"] ?? {};
+        if (rawConfig === null || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
+            errors.push(`connectors.json: entry '${name}' field 'config' must be an object. Got: ${Array.isArray(rawConfig) ? "array" : typeof rawConfig}.`);
+            continue;
+        }
+        // v0.4.1 env-block-as-scope: resolve `config.env` against process.env
+        // FIRST, then merge into the substitution scope for the rest of the
+        // config. Lets authors compose values like:
+        //   env: { AUTH_HEADER: "Bearer ${YOUTRACK_TOKEN}" }
+        //   args: ["--header", "Authorization:${AUTH_HEADER}"]
+        // Matches Claude Desktop's `mcp.json` convention.
+        let resolvedConfig;
+        try {
+            const cfgObj = rawConfig;
+            const rawEnv = cfgObj["env"];
+            let resolvedEnv;
+            let scopedEnv = env;
+            if (rawEnv !== undefined) {
+                if (rawEnv === null || typeof rawEnv !== "object" || Array.isArray(rawEnv)) {
+                    errors.push(`connectors.json: entry '${name}' field 'config.env' must be an object of string values.`);
+                    continue;
+                }
+                resolvedEnv = {};
+                for (const [k, v] of Object.entries(rawEnv)) {
+                    if (typeof v !== "string") {
+                        errors.push(`connectors.json: entry '${name}': config.env['${k}'] must be a string (got ${typeof v}).`);
+                        resolvedEnv = undefined;
+                        break;
+                    }
+                    resolvedEnv[k] = resolveEnvSubstitution(v, env);
+                }
+                if (resolvedEnv === undefined)
+                    continue;
+                scopedEnv = { ...env, ...resolvedEnv };
+            }
+            // Resolve the rest of the config using the scoped env (process.env
+            // plus the just-resolved env block). The env block itself goes in
+            // pre-resolved to skip a redundant second pass.
+            const restConfig = {};
+            for (const [k, v] of Object.entries(cfgObj)) {
+                if (k === "env") {
+                    if (resolvedEnv !== undefined)
+                        restConfig["env"] = resolvedEnv;
+                    continue;
+                }
+                restConfig[k] = resolveConfigEnv(v, scopedEnv);
+            }
+            resolvedConfig = restConfig;
+        }
+        catch (err) {
+            errors.push(`connectors.json: entry '${name}': ${err.message}`);
+            continue;
+        }
+        const classEntry = KNOWN_CONNECTOR_CLASSES.get(className);
+        if (classEntry === undefined) {
+            errors.push(`connectors.json: entry '${name}' references unknown connector class '${className}'. Known classes: ${listKnownConnectorClasses().join(", ")}.`);
+            continue;
+        }
+        let instance;
+        if (classEntry.fromConfig !== undefined) {
+            try {
+                instance = classEntry.fromConfig(resolvedConfig);
+            }
+            catch (err) {
+                errors.push(`connectors.json: entry '${name}' failed to instantiate '${className}': ${err.message}`);
+                continue;
+            }
+        }
+        else {
+            // No fromConfig means the class can't be JSON-instantiated. v0.4.0
+            // ships with CallbackMcpConnector in this state — wire it via
+            // embedder code. v0.4.1 adds RemoteMcpConnector with a fromConfig.
+            errors.push(`connectors.json: entry '${name}' uses class '${className}' which doesn't support configuration via connectors.json. Wire this connector via embedder code instead, or use a JSON-instantiable class.`);
+            continue;
+        }
+        // v0.4.1 — `allowed_tools` allowlist. Optional. Undefined = allow-all;
+        // [] = allow-none (staging disable); listed = exactly-these.
+        let allowedTools;
+        const rawAllowed = obj["allowed_tools"];
+        if (rawAllowed !== undefined) {
+            if (!Array.isArray(rawAllowed) || !rawAllowed.every((t) => typeof t === "string")) {
+                errors.push(`connectors.json: entry '${name}' field 'allowed_tools' must be an array of strings (got ${Array.isArray(rawAllowed) ? "array with non-string element" : typeof rawAllowed}).`);
+                continue;
+            }
+            allowedTools = rawAllowed;
+        }
+        connectors.push({
+            name,
+            className,
+            config: resolvedConfig,
+            instance,
+            ...(allowedTools !== undefined ? { allowedTools } : {}),
+        });
+    }
+    return { connectors, errors };
+}
+//# sourceMappingURL=config.js.map

package/dist/connectors/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/connectors/config.ts"],"names":[],"mappings":"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"}

package/dist/connectors/mcp-remote.d.ts

@@ -0,0 +1,79 @@
+import type { McpConnector, McpDispatchCtx, StaticCapabilities, ManifestInfo } from "./types.js";
+/** Wire-format options for stdio framing between this process and the spawned MCP child. */
+export type RemoteMcpFraming = "lsp" | "newline";
+/**
+ * Configuration shape for a `RemoteMcpConnector` in `connectors.json`.
+ * `${VAR}` substitutions are resolved at config-load time (v0.4.0); the
+ * resolved values arrive here verbatim. Extra fields (e.g. v0.4.x+
+ * `allowed_tools`) flow through the loader's permissive-field handling
+ * and are not validated by this constructor — they're handled at
+ * dispatch-policy layers above.
+ */
+export interface RemoteMcpConfig {
+    /** Executable to spawn. Typically `"npx"`, `"node"`, or a binary path. */
+    command: string;
+    /** Argument list for the spawned process. */
+    args: string[];
+    /** Environment variables for the spawned child. Merged with parent env. */
+    env?: Record<string, string>;
+    /** Stdio framing convention. Default: `"lsp"`. */
+    framing?: RemoteMcpFraming;
+    /** Maximum time (ms) to wait for the `initialize` response. Default: 10000. */
+    initTimeoutMs?: number;
+    /** Maximum time (ms) to wait for a `tools/call` response. Default: 30000. */
+    callTimeoutMs?: number;
+    /** Maximum time (ms) to wait for graceful shutdown before SIGKILL. Default: 2000. */
+    shutdownTimeoutMs?: number;
+}
+/** Connector dispatch error — bridge-side failures surface to skill via this. */
+export declare class RemoteMcpDispatchError extends Error {
+    readonly bridgeCause: unknown;
+    constructor(message: string, bridgeCause?: unknown);
+}
+export declare class RemoteMcpConnector implements McpConnector {
+    private readonly config;
+    static staticCapabilities(): StaticCapabilities;
+    /**
+     * Closed-set registry factory. Validates config shape, constructs the
+     * instance. The spawn + handshake are deferred to first dispatch (or
+     * an explicit `start()` call) so config validation can happen
+     * synchronously at load time.
+     */
+    static fromConfig(config: Record<string, unknown>): RemoteMcpConnector;
+    private child;
+    private nextRequestId;
+    private pending;
+    private inboundBuffer;
+    private initializePromise;
+    private toolsAvailable;
+    private errorState;
+    private readonly framing;
+    private readonly initTimeoutMs;
+    private readonly callTimeoutMs;
+    private readonly shutdownTimeoutMs;
+    constructor(config: RemoteMcpConfig);
+    /**
+     * Spawn the child + run the `initialize` handshake. Idempotent;
+     * subsequent calls return the same in-flight or completed promise.
+     * Called lazily by `call()` on first dispatch.
+     */
+    start(): Promise<unknown>;
+    private doStart;
+    call(toolName: string, args: Record<string, unknown>, _ctxOverrides?: McpDispatchCtx): Promise<unknown>;
+    manifest(): Promise<ManifestInfo>;
+    /**
+     * Graceful shutdown. Best-effort `shutdown` JSON-RPC request, then
+     * SIGTERM, then SIGKILL fallback after `shutdownTimeoutMs`. Idempotent.
+     */
+    dispose(): Promise<void>;
+    /** For tests + observability — names of tools surfaced by the initialize handshake. */
+    getToolsAvailable(): readonly string[];
+    private sendRequest;
+    private encodeFrame;
+    private drainInbound;
+    private drainLsp;
+    private drainNewline;
+    private handleInboundMessage;
+    private rejectAllPending;
+}
+//# sourceMappingURL=mcp-remote.d.ts.map

package/dist/connectors/mcp-remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-remote.d.ts","sourceRoot":"","sources":["../../src/connectors/mcp-remote.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,YAAY,EACb,MAAM,YAAY,CAAC;AAIpB,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,kDAAkD;IAClD,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAsBD,iFAAiF;AACjF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,WAAW,EAAE,OAAO,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO;CAKnD;AAED,qBAAa,kBAAmB,YAAW,YAAY;IAgEzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IA/DnC,MAAM,CAAC,kBAAkB,IAAI,kBAAkB;IAa/C;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB;IAgCtE,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAEd,MAAM,EAAE,eAAe;IAOpD;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;YAMX,OAAO;IAoDf,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,aAAa,CAAC,EAAE,cAAc,GAC7B,OAAO,CAAC,OAAO,CAAC;IA2Bb,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC;IAcvC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B9B,uFAAuF;IACvF,iBAAiB,IAAI,SAAS,MAAM,EAAE;IAMtC,OAAO,CAAC,WAAW;IA+BnB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,QAAQ;IAoBhB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,gBAAgB;CAOzB"}