clinkx 0.1.0

package/dist/config.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+const RoleConfigSchema = z.object({
+    inline_prompt: z.string().optional(),
+    prompt_file: z.string().optional(),
+});
+const ResultContractSchema = z.object({
+    enabled: z.boolean().default(false),
+    filename: z.enum(["RESULT.md", "RESULT.json"]).default("RESULT.md"),
+});
+/**
+ * CLI adapter config schema — defines how ClinkX talks to a particular CLI.
+ *
+ * All fields from the plan: name, command, runner, args, unsafe_args, env,
+ * env_allowlist, timeout_seconds, parser, capabilities_hint, roles,
+ * supports_images, requires_tty, result_contract, prompt_mode.
+ */
+export const CliAdapterConfigSchema = z.object({
+    name: z.string().min(1),
+    command: z.string().min(1),
+    runner: z.string().optional(),
+    args: z.array(z.string()).default([]),
+    unsafe_args: z.array(z.string()).default([]),
+    env: z.record(z.string()).default({}),
+    env_allowlist: z.array(z.string()).default([]),
+    timeout_seconds: z.number().positive().default(600),
+    parser: z
+        .enum(["text", "json_extract", "gemini_json", "codex_jsonl", "claude_json"])
+        .default("text"),
+    tolerate_nonzero_exit_for_parse: z.boolean().default(false),
+    capabilities_hint: z.string().optional(),
+    roles: z.record(RoleConfigSchema).default({}),
+    supports_images: z.boolean().default(false),
+    requires_tty: z.boolean().default(false),
+    result_contract: ResultContractSchema.default({
+        enabled: false,
+        filename: "RESULT.md",
+    }),
+    prompt_mode: z.enum(["stdin", "arg", "file"]).default("stdin"),
+});
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAIH,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;CACpE,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC5C,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC9C,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACnD,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,CAAC,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;SAC3E,OAAO,CAAC,MAAM,CAAC;IAClB,+BAA+B,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC3D,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACxC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7C,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC3C,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACxC,eAAe,EAAE,oBAAoB,CAAC,OAAO,CAAC;QAC5C,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,WAAW;KACtB,CAAC;IACF,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;CAC/D,CAAC,CAAC"}

package/dist/continuation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bounded LRU cache for continuation context.
+ *
+ * Stores the final output from previous runs, keyed by continuation_id.
+ * When capacity is reached, the least-recently-used entry is evicted.
+ */
+export declare class ContinuationCache {
+    private readonly maxEntries;
+    private readonly cache;
+    constructor(maxEntries?: number);
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    get size(): number;
+    clear(): void;
+}

package/dist/continuation.js

@@ -0,0 +1,42 @@
+const DEFAULT_MAX_ENTRIES = 50;
+/**
+ * Bounded LRU cache for continuation context.
+ *
+ * Stores the final output from previous runs, keyed by continuation_id.
+ * When capacity is reached, the least-recently-used entry is evicted.
+ */
+export class ContinuationCache {
+    maxEntries;
+    cache = new Map();
+    constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+        this.maxEntries = maxEntries;
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value != null) {
+            // Move to end (most recently used)
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        if (this.cache.size >= this.maxEntries) {
+            const oldest = this.cache.keys().next();
+            if (!oldest.done) {
+                this.cache.delete(oldest.value);
+            }
+        }
+        this.cache.set(key, value);
+    }
+    get size() {
+        return this.cache.size;
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=continuation.js.map

package/dist/continuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation.js","sourceRoot":"","sources":["../src/continuation.ts"],"names":[],"mappings":"AAAA,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IACX,UAAU,CAAS;IACnB,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEnD,YAAY,UAAU,GAAG,mBAAmB;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;YAClB,mCAAmC;YACnC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAa;QAC5B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACjB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+import type { CliAdapterConfig } from "./config.js";
+/**
+ * Build a sanitized environment for subprocess execution.
+ *
+ * Starts from minimal baseline (PATH/HOME/USER/LANG/TMPDIR),
+ * adds adapter-defined env, then allowlisted vars from host process.
+ */
+export declare function buildEnv(adapter: CliAdapterConfig, extraEnv?: Record<string, string>): Record<string, string>;
+/** Redact env values that look like secrets (for logging). */
+export declare function redactSecrets(env: Record<string, string>): Record<string, string>;

package/dist/env.js

@@ -0,0 +1,52 @@
+const BASELINE_VARS = ["PATH", "HOME", "USER", "LANG", "TMPDIR"];
+const SECRET_PATTERNS = [
+    /KEY/i,
+    /SECRET/i,
+    /TOKEN/i,
+    /PASSWORD/i,
+    /CREDENTIAL/i,
+];
+/**
+ * Build a sanitized environment for subprocess execution.
+ *
+ * Starts from minimal baseline (PATH/HOME/USER/LANG/TMPDIR),
+ * adds adapter-defined env, then allowlisted vars from host process.
+ */
+export function buildEnv(adapter, extraEnv) {
+    const env = {};
+    // 1. Baseline vars from current process
+    for (const key of BASELINE_VARS) {
+        const val = process.env[key];
+        if (val != null) {
+            env[key] = val;
+        }
+    }
+    // 2. Adapter-defined env
+    for (const [key, val] of Object.entries(adapter.env)) {
+        env[key] = val;
+    }
+    // 3. Allowlisted vars from current process
+    for (const key of adapter.env_allowlist) {
+        const val = process.env[key];
+        if (val != null) {
+            env[key] = val;
+        }
+    }
+    // 4. Extra env (e.g., run-dir path)
+    if (extraEnv) {
+        for (const [key, val] of Object.entries(extraEnv)) {
+            env[key] = val;
+        }
+    }
+    return env;
+}
+/** Redact env values that look like secrets (for logging). */
+export function redactSecrets(env) {
+    const redacted = {};
+    for (const [key, val] of Object.entries(env)) {
+        const isSecret = SECRET_PATTERNS.some((p) => p.test(key));
+        redacted[key] = isSecret ? "[REDACTED]" : val;
+    }
+    return redacted;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEjE,MAAM,eAAe,GAAG;IACtB,MAAM;IACN,SAAS;IACT,QAAQ;IACR,WAAW;IACX,aAAa;CACd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,OAAyB,EACzB,QAAiC;IAEjC,MAAM,GAAG,GAA2B,EAAE,CAAC;IAEvC,wCAAwC;IACxC,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;YAChB,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QACjB,CAAC;IACH,CAAC;IAED,yBAAyB;IACzB,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,2CAA2C;IAC3C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;YAChB,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QACjB,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAC3B,GAA2B;IAE3B,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Base error for all ClinkX-specific failures.
+ */
+export declare class ClinkxError extends Error {
+    constructor(message: string);
+}
+/**
+ * Invalid parameters — maps to JSON-RPC -32602.
+ *
+ * Thrown for protocol-level input errors (bad schema, unknown cli_name, etc.).
+ * The MCP SDK's McpError with ErrorCode.InvalidParams handles the wire encoding.
+ */
+export declare class InvalidParamsError extends ClinkxError {
+    constructor(message: string);
+}
+/**
+ * Execution failure — maps to tool response with isError:true.
+ *
+ * Used for runtime failures (CLI not found, timeout, non-zero exit, etc.).
+ * These are NOT JSON-RPC errors; they are valid tool responses that signal failure.
+ */
+export declare class ExecutionError extends ClinkxError {
+    constructor(message: string);
+}
+/**
+ * Convert an InvalidParamsError to an MCP SDK McpError (-32602).
+ *
+ * The SDK will serialize this as a proper JSON-RPC error response.
+ */
+export declare function toMcpInvalidParams(err: InvalidParamsError): McpError;
+/**
+ * Build an MCP tool result indicating execution failure.
+ *
+ * Returns { content: [{ type: "text", text }], isError: true }.
+ * This is the correct MCP response shape for runtime failures:
+ * the tool executed, but produced an error result.
+ */
+export declare function toMcpExecutionError(err: ExecutionError): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
+/**
+ * Cancellation — request was cancelled via MCP notifications/cancelled.
+ *
+ * Per MCP spec: "The receiver MUST NOT send a response to the request."
+ * When this is thrown, the caller should NOT produce any response.
+ */
+export declare class CancellationError extends ClinkxError {
+    constructor();
+}
+/**
+ * Classify an unknown error and produce the appropriate MCP response.
+ *
+ * - InvalidParamsError → throw McpError (JSON-RPC -32602)
+ * - ExecutionError → return { isError: true } tool result
+ * - Unknown → return { isError: true } tool result with generic message
+ */
+export declare function handleToolError(err: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};

package/dist/errors.js

@@ -0,0 +1,88 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Base error for all ClinkX-specific failures.
+ */
+export class ClinkxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ClinkxError";
+    }
+}
+/**
+ * Invalid parameters — maps to JSON-RPC -32602.
+ *
+ * Thrown for protocol-level input errors (bad schema, unknown cli_name, etc.).
+ * The MCP SDK's McpError with ErrorCode.InvalidParams handles the wire encoding.
+ */
+export class InvalidParamsError extends ClinkxError {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidParamsError";
+    }
+}
+/**
+ * Execution failure — maps to tool response with isError:true.
+ *
+ * Used for runtime failures (CLI not found, timeout, non-zero exit, etc.).
+ * These are NOT JSON-RPC errors; they are valid tool responses that signal failure.
+ */
+export class ExecutionError extends ClinkxError {
+    constructor(message) {
+        super(message);
+        this.name = "ExecutionError";
+    }
+}
+/**
+ * Convert an InvalidParamsError to an MCP SDK McpError (-32602).
+ *
+ * The SDK will serialize this as a proper JSON-RPC error response.
+ */
+export function toMcpInvalidParams(err) {
+    return new McpError(ErrorCode.InvalidParams, err.message);
+}
+/**
+ * Build an MCP tool result indicating execution failure.
+ *
+ * Returns { content: [{ type: "text", text }], isError: true }.
+ * This is the correct MCP response shape for runtime failures:
+ * the tool executed, but produced an error result.
+ */
+export function toMcpExecutionError(err) {
+    return {
+        content: [{ type: "text", text: err.message }],
+        isError: true,
+    };
+}
+/**
+ * Cancellation — request was cancelled via MCP notifications/cancelled.
+ *
+ * Per MCP spec: "The receiver MUST NOT send a response to the request."
+ * When this is thrown, the caller should NOT produce any response.
+ */
+export class CancellationError extends ClinkxError {
+    constructor() {
+        super("Request cancelled");
+        this.name = "CancellationError";
+    }
+}
+/**
+ * Classify an unknown error and produce the appropriate MCP response.
+ *
+ * - InvalidParamsError → throw McpError (JSON-RPC -32602)
+ * - ExecutionError → return { isError: true } tool result
+ * - Unknown → return { isError: true } tool result with generic message
+ */
+export function handleToolError(err) {
+    if (err instanceof InvalidParamsError) {
+        throw toMcpInvalidParams(err);
+    }
+    if (err instanceof ExecutionError) {
+        return toMcpExecutionError(err);
+    }
+    const message = err instanceof Error ? err.message : "Unknown execution error";
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAuB;IACxD,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAmB;IAIrD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAC9C,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IAChD;QACE,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAI1C,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;QACtC,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;QAClC,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,OAAO,GACX,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,yBAAyB,CAAC;IACjE,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/handler.d.ts

@@ -0,0 +1,21 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+/**
+ * Handle a clink tool invocation.
+ *
+ * 1. Validate input against the frozen zod schema.
+ * 2. On validation failure: throw InvalidParamsError (→ -32602).
+ * 3. Execute the full pipeline: resolve → prompt → exec → parse → return.
+ */
+export declare function handleClink(rawInput: unknown, options?: {
+    signal?: AbortSignal;
+    progress?: {
+        server: Server;
+        token: string | number;
+    };
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/handler.js

@@ -0,0 +1,45 @@
+import { ClinkInputSchema } from "./schema.js";
+import { InvalidParamsError } from "./errors.js";
+import { executePipeline } from "./pipeline.js";
+import { AdapterRegistry } from "./registry.js";
+import { logger } from "./logger.js";
+function formatZodError(err) {
+    return err.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+// Lazy-loaded singleton registry
+let registry;
+function getRegistry() {
+    if (!registry) {
+        registry = AdapterRegistry.load();
+    }
+    return registry;
+}
+/**
+ * Handle a clink tool invocation.
+ *
+ * 1. Validate input against the frozen zod schema.
+ * 2. On validation failure: throw InvalidParamsError (→ -32602).
+ * 3. Execute the full pipeline: resolve → prompt → exec → parse → return.
+ */
+export async function handleClink(rawInput, options) {
+    const parseResult = ClinkInputSchema.safeParse(rawInput);
+    if (!parseResult.success) {
+        const detail = formatZodError(parseResult.error);
+        throw new InvalidParamsError(`Invalid clink input: ${detail}`);
+    }
+    const input = parseResult.data;
+    logger.debug({ cli_name: input.cli_name, role: input.role }, "clink invoked");
+    const pipelineOptions = options?.signal != null || options?.progress != null
+        ? {
+            ...(options?.signal != null ? { signal: options.signal } : {}),
+            ...(options?.progress != null ? { progress: options.progress } : {}),
+        }
+        : undefined;
+    return await executePipeline(input, getRegistry(), pipelineOptions);
+}
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC,SAAS,cAAc,CAAC,GAAa;IACnC,OAAO,GAAG,CAAC,MAAM;SACd,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,iCAAiC;AACjC,IAAI,QAAqC,CAAC;AAE1C,SAAS,WAAW;IAClB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC;IACpC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAiB,EACjB,OAGC;IAKD,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACzD,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACjD,MAAM,IAAI,kBAAkB,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC;IAC/B,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,eAAe,CAAC,CAAC;IAE9E,MAAM,eAAe,GACnB,OAAO,EAAE,MAAM,IAAI,IAAI,IAAI,OAAO,EAAE,QAAQ,IAAI,IAAI;QAClD,CAAC,CAAC;YACE,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE;QACH,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO,MAAM,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,eAAe,CAAC,CAAC;AACtE,CAAC"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { logger, assertStderrLogger } from "./logger.js";
+import { assertNotRootDir } from "./paths.js";
+import { killAllActive } from "./runner.js";
+/**
+ * ClinkX MCP server entry point.
+ *
+ * 1. Verify logger writes to stderr (STDIO correctness invariant).
+ * 2. Create the MCP server with tool handlers.
+ * 3. Connect STDIO transport (stdin/stdout for JSON-RPC, stderr for logs).
+ */
+async function main() {
+    // Startup self-check: logger must target stderr
+    assertStderrLogger();
+    // Startup safety guard: refuse running from filesystem root unless explicitly allowlisted
+    assertNotRootDir();
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    logger.info("ClinkX MCP server starting (STDIO transport)");
+    await server.connect(transport);
+    // Graceful shutdown: kill active subprocesses, close server, exit
+    const shutdown = async () => {
+        logger.info("shutdown signal received, cleaning up");
+        killAllActive();
+        await server.close();
+        process.exit(0);
+    };
+    process.once("SIGTERM", () => void shutdown().catch(() => process.exit(1)));
+    process.once("SIGINT", () => void shutdown().catch(() => process.exit(1)));
+    logger.info("ClinkX MCP server connected and ready");
+}
+main().catch((err) => {
+    logger.fatal({ err }, "ClinkX failed to start");
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;GAMG;AACH,KAAK,UAAU,IAAI;IACjB,gDAAgD;IAChD,kBAAkB,EAAE,CAAC;IACrB,0FAA0F;IAC1F,gBAAgB,EAAE,CAAC;IAEnB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAE5D,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,kEAAkE;IAClE,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,MAAM,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;QACrD,aAAa,EAAE,CAAC;QAChB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3E,MAAM,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;AACvD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,wBAAwB,CAAC,CAAC;IAChD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,16 @@
+import pino from "pino";
+/**
+ * ClinkX logger — writes exclusively to stderr (fd 2).
+ *
+ * STDIO correctness is a hard invariant: stdout is reserved for
+ * MCP JSON-RPC frames. All diagnostic output goes to stderr.
+ */
+export declare const logger: pino.Logger<never, boolean>;
+/**
+ * Startup self-check: verify logger writes to stderr, not stdout.
+ * Fails fast if the invariant is violated.
+ *
+ * We inspect the pino SonicBoom destination's `fd` property
+ * to confirm it points at fd 2 (stderr).
+ */
+export declare function assertStderrLogger(): void;

package/dist/logger.js

@@ -0,0 +1,30 @@
+import pino from "pino";
+const LOG_LEVEL = process.env["CLINKX_LOG_LEVEL"] ?? "info";
+// Construct the stderr destination explicitly so we can inspect it.
+const stderrDestination = pino.destination({ fd: 2, sync: false });
+/**
+ * ClinkX logger — writes exclusively to stderr (fd 2).
+ *
+ * STDIO correctness is a hard invariant: stdout is reserved for
+ * MCP JSON-RPC frames. All diagnostic output goes to stderr.
+ */
+export const logger = pino({
+    name: "clinkx",
+    level: LOG_LEVEL,
+}, stderrDestination);
+/**
+ * Startup self-check: verify logger writes to stderr, not stdout.
+ * Fails fast if the invariant is violated.
+ *
+ * We inspect the pino SonicBoom destination's `fd` property
+ * to confirm it points at fd 2 (stderr).
+ */
+export function assertStderrLogger() {
+    const dest = stderrDestination;
+    const fd = dest.fd;
+    if (fd !== 2) {
+        throw new Error(`FATAL: logger destination fd=${String(fd)}, expected fd=2 (stderr). ` +
+            "STDIO correctness requires all logging to stderr.");
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,MAAM,CAAC;AAE5D,oEAAoE;AACpE,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CACxB;IACE,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,SAAS;CACjB,EACD,iBAAiB,CAClB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,IAAI,GAAG,iBAA+C,CAAC;IAC7D,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,gCAAgC,MAAM,CAAC,EAAE,CAAC,4BAA4B;YACpE,mDAAmD,CACtD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/parsers/claude-json.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "./types.js";
+export declare const claudeJsonParser: Parser;

package/dist/parsers/claude-json.js

@@ -0,0 +1,58 @@
+import { findFirstJsonBlock, preferredText } from "./utils.js";
+function parseMaybeJson(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        const block = findFirstJsonBlock(text);
+        return block?.value ?? null;
+    }
+}
+function extractClaudeResultText(value) {
+    if (value == null || typeof value !== "object")
+        return null;
+    const root = value;
+    const result = root["result"];
+    if (typeof result === "string")
+        return result;
+    if (Array.isArray(result)) {
+        const texts = result
+            .map((item) => {
+            if (typeof item === "string")
+                return item;
+            if (item && typeof item === "object") {
+                const r = item;
+                if (typeof r["text"] === "string")
+                    return r["text"];
+                if (typeof r["content"] === "string")
+                    return r["content"];
+            }
+            return "";
+        })
+            .filter((t) => t.length > 0);
+        return texts.length > 0 ? texts.join("") : null;
+    }
+    return null;
+}
+export const claudeJsonParser = {
+    name: "claude_json",
+    preferredBuffers: ["stdoutHead", "stdoutTail"],
+    parse(input) {
+        const text = preferredText(input, ["stdoutHead", "stdoutTail"]);
+        const parsed = parseMaybeJson(text);
+        if (parsed == null)
+            return null;
+        const extracted = extractClaudeResultText(parsed);
+        if (extracted == null)
+            return null;
+        return {
+            content: extracted,
+            source: "parser",
+            metadata: { parser: "claude_json" },
+        };
+    },
+};
+//# sourceMappingURL=claude-json.js.map

package/dist/parsers/claude-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-json.js","sourceRoot":"","sources":["../../src/parsers/claude-json.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D,SAAS,cAAc,CAAC,IAAY;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,KAAK,EAAE,KAAK,IAAI,IAAI,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAc;IAC7C,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,IAAI,GAAG,KAAgC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE9B,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAE9C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,MAAM;aACjB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACZ,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC1C,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrC,MAAM,CAAC,GAAG,IAA+B,CAAC;gBAC1C,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;oBAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;gBACpD,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ;oBAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC;YAC5D,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;aACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAW;IACtC,IAAI,EAAE,aAAa;IACnB,gBAAgB,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;QAChE,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,MAAM,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAEhC,MAAM,SAAS,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,SAAS,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAEnC,OAAO;YACL,OAAO,EAAE,SAAS;YAClB,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;SACpC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/parsers/codex-jsonl.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "./types.js";
+export declare const codexJsonlParser: Parser;