clinkx 0.1.0

package/dist/parsers/codex-jsonl.js

@@ -0,0 +1,75 @@
+import { preferredText } from "./utils.js";
+function extractCodexMessageText(value) {
+    if (value == null || typeof value !== "object")
+        return null;
+    const rec = value;
+    // Common: { type: "message", message: { role, content } }
+    const message = rec["message"] ??
+        rec["data"];
+    const maybeMsg = message ?? rec;
+    const content = maybeMsg["content"];
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const text = content
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            if (part && typeof part === "object") {
+                const pr = part;
+                if (typeof pr["text"] === "string")
+                    return pr["text"];
+                if (typeof pr["content"] === "string")
+                    return pr["content"];
+            }
+            return "";
+        })
+            .filter((t) => t.length > 0)
+            .join("");
+        return text.length > 0 ? text : null;
+    }
+    if (typeof rec["output_text"] === "string")
+        return rec["output_text"];
+    // Codex item.completed events: { type: "item.completed", item: { text: "..." } }
+    const item = rec["item"];
+    if (item != null && typeof item === "object" && typeof item["text"] === "string") {
+        return item["text"];
+    }
+    return null;
+}
+export const codexJsonlParser = {
+    name: "codex_jsonl",
+    preferredBuffers: ["stdoutTail", "stdoutHead"],
+    parse(input) {
+        const parseJsonl = (text) => {
+            const lines = text
+                .split("\n")
+                .map((l) => l.trim())
+                .filter((l) => l.length > 0);
+            let lastContent = null;
+            for (const line of lines) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const content = extractCodexMessageText(parsed);
+                if (content != null)
+                    lastContent = content;
+            }
+            return lastContent;
+        };
+        const fromTail = parseJsonl(preferredText(input, ["stdoutTail"]));
+        const lastContent = fromTail ?? parseJsonl(preferredText(input, ["stdoutHead"]));
+        if (lastContent == null)
+            return null;
+        return {
+            content: lastContent,
+            source: "parser",
+            metadata: { parser: "codex_jsonl" },
+        };
+    },
+};
+//# sourceMappingURL=codex-jsonl.js.map

package/dist/parsers/codex-jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-jsonl.js","sourceRoot":"","sources":["../../src/parsers/codex-jsonl.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,SAAS,uBAAuB,CAAC,KAAc;IAC7C,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,0DAA0D;IAC1D,MAAM,OAAO,GACV,GAAG,CAAC,SAAS,CAAyC;QACtD,GAAG,CAAC,MAAM,CAAyC,CAAC;IAEvD,MAAM,QAAQ,GAAG,OAAO,IAAI,GAAG,CAAC;IAEhC,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAEhD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,OAAO;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,EAAE,GAAG,IAA+B,CAAC;gBAC3C,IAAI,OAAO,EAAE,CAAC,MAAM,CAAC,KAAK,QAAQ;oBAAE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;gBACtD,IAAI,OAAO,EAAE,CAAC,SAAS,CAAC,KAAK,QAAQ;oBAAE,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;YAC9D,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;aACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;aAC3B,IAAI,CAAC,EAAE,CAAC,CAAC;QACZ,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,aAAa,CAAC,CAAC;IAEtE,iFAAiF;IACjF,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAwC,CAAC;IAChE,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;QACjF,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,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,UAAU,GAAG,CAAC,IAAY,EAAiB,EAAE;YACjD,MAAM,KAAK,GAAG,IAAI;iBACf,KAAK,CAAC,IAAI,CAAC;iBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;iBACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAE/B,IAAI,WAAW,GAAkB,IAAI,CAAC;YACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,MAAe,CAAC;gBACpB,IAAI,CAAC;oBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;gBACvC,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS;gBACX,CAAC;gBACD,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;gBAChD,IAAI,OAAO,IAAI,IAAI;oBAAE,WAAW,GAAG,OAAO,CAAC;YAC7C,CAAC;YACD,OAAO,WAAW,CAAC;QACrB,CAAC,CAAC;QAEF,MAAM,QAAQ,GAAG,UAAU,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAClE,MAAM,WAAW,GACf,QAAQ,IAAI,UAAU,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC/D,IAAI,WAAW,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;SACpC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/parsers/extract.d.ts

@@ -0,0 +1,25 @@
+import type { ParseInput, ParseResult } from "./types.js";
+export interface ExtractInput extends ParseInput {
+    exitCode: number | null;
+    /**
+     * Default: false (non-zero exit => isError:true).
+     * When true, non-zero exits are tolerated if we can parse a valid payload.
+     */
+    tolerateNonzeroExitForParse?: boolean;
+}
+export interface ExtractOutput {
+    result: ParseResult;
+    isError: boolean;
+    exitCode: number | null;
+}
+/**
+ * Deterministically extract the final user-facing content from captured buffers.
+ *
+ * Order:
+ * 1) result contract file (if enabled + present)
+ * 2) adapter-specific parser
+ * 3) generic json_extract
+ * 4) <SUMMARY> extraction
+ * 5) raw stdout fallback
+ */
+export declare function extractResult(input: ExtractInput): Promise<ExtractOutput>;

package/dist/parsers/extract.js

@@ -0,0 +1,87 @@
+import { joinBuffers, preferredText } from "./utils.js";
+import { textParser } from "./text.js";
+import { jsonExtractParser } from "./json-extract.js";
+import { geminiJsonParser } from "./gemini-json.js";
+import { codexJsonlParser } from "./codex-jsonl.js";
+import { claudeJsonParser } from "./claude-json.js";
+import { extractSummary } from "./summary.js";
+import { readResultFile } from "../result-contract.js";
+const PARSERS = [
+    textParser,
+    jsonExtractParser,
+    geminiJsonParser,
+    codexJsonlParser,
+    claudeJsonParser,
+];
+function parserByName(name) {
+    return PARSERS.find((p) => p.name === name) ?? null;
+}
+async function tryReadResultContract(workdir, contract) {
+    if (!contract?.enabled)
+        return null;
+    if (contract.filename.trim().length === 0)
+        return null;
+    return readResultFile(workdir, contract.filename);
+}
+function rawStdoutFallback(input) {
+    // JSONL adapters emit final events late; prefer tail.
+    const preferTailFirst = input.adapter.parser === "codex_jsonl" || input.adapter.parser === "jsonl";
+    const content = preferTailFirst
+        ? input.stdoutTail.length > 0
+            ? input.stdoutTail
+            : input.stdoutHead
+        : joinBuffers([input.stdoutHead, input.stdoutTail]);
+    return { content, source: "raw_fallback" };
+}
+function hasValidPayload(result) {
+    return result.content.trim().length > 0;
+}
+/**
+ * Deterministically extract the final user-facing content from captured buffers.
+ *
+ * Order:
+ * 1) result contract file (if enabled + present)
+ * 2) adapter-specific parser
+ * 3) generic json_extract
+ * 4) <SUMMARY> extraction
+ * 5) raw stdout fallback
+ */
+export async function extractResult(input) {
+    const contractText = await tryReadResultContract(input.workdir, input.adapter.result_contract);
+    let result = contractText != null
+        ? {
+            content: contractText,
+            source: "result_contract",
+            metadata: { filename: input.adapter.result_contract?.filename },
+        }
+        : null;
+    if (result == null) {
+        const adapterParser = parserByName(input.adapter.parser);
+        result = adapterParser?.parse(input) ?? null;
+    }
+    if (result == null && input.adapter.parser !== "json_extract") {
+        result = jsonExtractParser.parse(input) ?? null;
+    }
+    if (result == null) {
+        const stdoutCombined = preferredText(input, ["stdoutHead", "stdoutTail"]);
+        const summary = extractSummary(stdoutCombined);
+        if (summary != null) {
+            result = { content: summary, source: "summary" };
+        }
+    }
+    if (result == null) {
+        result = rawStdoutFallback(input);
+    }
+    // Error recovery parity: always attempt extraction, even on non-zero exit.
+    const exitCode = input.exitCode;
+    const tolerate = input.tolerateNonzeroExitForParse ?? false;
+    const isError = exitCode === 0
+        ? false
+        : exitCode == null
+            ? true
+            : tolerate && hasValidPayload(result)
+                ? false
+                : true;
+    return { result, isError, exitCode };
+}
+//# sourceMappingURL=extract.js.map

package/dist/parsers/extract.js.map

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

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

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

package/dist/parsers/gemini-json.js

@@ -0,0 +1,72 @@
+import { findFirstJsonBlock, preferredText } from "./utils.js";
+function extractGeminiText(value) {
+    if (value == null || typeof value !== "object")
+        return null;
+    const root = value;
+    // Simple { "response": "text" } format (PAL parity)
+    if (typeof root["response"] === "string") {
+        return root["response"].trim() || null;
+    }
+    const response = root["response"] ?? root;
+    const candidates = response["candidates"];
+    if (!Array.isArray(candidates))
+        return null;
+    for (const cand of candidates) {
+        if (cand == null || typeof cand !== "object")
+            continue;
+        const c = cand;
+        const content = c["content"];
+        if (content && typeof content === "object") {
+            const contentObj = content;
+            const parts = contentObj["parts"];
+            if (Array.isArray(parts)) {
+                const texts = parts
+                    .map((p) => {
+                    if (p && typeof p === "object") {
+                        const pr = p;
+                        if (typeof pr["text"] === "string")
+                            return pr["text"];
+                    }
+                    return "";
+                })
+                    .filter((t) => t.length > 0);
+                if (texts.length > 0)
+                    return texts.join("");
+            }
+        }
+        if (typeof c["text"] === "string")
+            return c["text"];
+    }
+    return null;
+}
+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;
+    }
+}
+export const geminiJsonParser = {
+    name: "gemini_json",
+    preferredBuffers: ["stdoutHead", "stdoutTail"],
+    parse(input) {
+        const text = preferredText(input, ["stdoutHead", "stdoutTail"]);
+        const parsed = parseMaybeJson(text);
+        if (parsed == null)
+            return null;
+        const extracted = extractGeminiText(parsed);
+        if (extracted == null)
+            return null;
+        return {
+            content: extracted,
+            source: "parser",
+            metadata: { parser: "gemini_json" },
+        };
+    },
+};
+//# sourceMappingURL=gemini-json.js.map

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

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

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

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

package/dist/parsers/json-extract.js

@@ -0,0 +1,19 @@
+import { findFirstJsonBlock, extractTextFromContentField, preferredText } from "./utils.js";
+export const jsonExtractParser = {
+    name: "json_extract",
+    preferredBuffers: ["stdoutHead", "stdoutTail"],
+    parse(input) {
+        const text = preferredText(input, ["stdoutHead", "stdoutTail"]);
+        const block = findFirstJsonBlock(text);
+        if (block == null)
+            return null;
+        const fromContent = extractTextFromContentField(block.value);
+        const content = fromContent ?? JSON.stringify(block.value);
+        return {
+            content,
+            source: "json_extract",
+            metadata: { parser: "json_extract" },
+        };
+    },
+};
+//# sourceMappingURL=json-extract.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-extract.js","sourceRoot":"","sources":["../../src/parsers/json-extract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5F,MAAM,CAAC,MAAM,iBAAiB,GAAW;IACvC,IAAI,EAAE,cAAc;IACpB,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,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAE/B,MAAM,WAAW,GAAG,2BAA2B,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,WAAW,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAE3D,OAAO;YACL,OAAO;YACP,MAAM,EAAE,cAAc;YACtB,QAAQ,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE;SACrC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/parsers/summary.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extract a user-facing summary wrapped in <SUMMARY>...</SUMMARY>.
+ *
+ * Designed as a late-stage fallback: it ignores any tool noise outside the tags
+ * and preserves user formatting inside the tags.
+ */
+export declare function extractSummary(text: string): string | null;

package/dist/parsers/summary.js

@@ -0,0 +1,29 @@
+import { normalizeNewlines } from "./utils.js";
+function trimBlankEdges(text) {
+    const lines = normalizeNewlines(text).split("\n");
+    while (lines.length > 0 && lines[0].trim().length === 0)
+        lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1].trim().length === 0)
+        lines.pop();
+    return lines.join("\n");
+}
+/**
+ * Extract a user-facing summary wrapped in <SUMMARY>...</SUMMARY>.
+ *
+ * Designed as a late-stage fallback: it ignores any tool noise outside the tags
+ * and preserves user formatting inside the tags.
+ */
+export function extractSummary(text) {
+    const normalized = normalizeNewlines(text);
+    const re = /<SUMMARY>([\s\S]*?)<\/SUMMARY>/gi;
+    let match;
+    let lastContent = null;
+    while ((match = re.exec(normalized)) !== null) {
+        lastContent = match[1];
+    }
+    if (lastContent == null)
+        return null;
+    const cleaned = trimBlankEdges(lastContent);
+    return cleaned.length > 0 ? cleaned : null;
+}
+//# sourceMappingURL=summary.js.map

package/dist/parsers/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/parsers/summary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,SAAS,cAAc,CAAC,IAAY;IAClC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IACxE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QACrE,KAAK,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,EAAE,GAAG,kCAAkC,CAAC;IAC9C,IAAI,KAA6B,CAAC;IAClC,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9C,WAAW,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC1B,CAAC;IACD,IAAI,WAAW,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC"}

package/dist/parsers/text.d.ts

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

package/dist/parsers/text.js

@@ -0,0 +1,14 @@
+import { preferredText } from "./utils.js";
+export const textParser = {
+    name: "text",
+    preferredBuffers: ["stdoutHead", "stdoutTail"],
+    parse(input) {
+        const content = preferredText(input, ["stdoutHead", "stdoutTail"]);
+        return {
+            content,
+            source: "parser",
+            metadata: { parser: "text" },
+        };
+    },
+};
+//# sourceMappingURL=text.js.map

package/dist/parsers/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/parsers/text.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,CAAC,MAAM,UAAU,GAAW;IAChC,IAAI,EAAE,MAAM;IACZ,gBAAgB,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C,KAAK,CAAC,KAAK;QACT,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;QACnE,OAAO;YACL,OAAO;YACP,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;SAC7B,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/parsers/types.d.ts

@@ -0,0 +1,25 @@
+export interface ParseInput {
+    stdoutHead: string;
+    stdoutTail: string;
+    stderrHead: string;
+    stderrTail: string;
+    workdir: string;
+    adapter: {
+        name: string;
+        parser: string;
+        result_contract?: {
+            enabled: boolean;
+            filename: string;
+        };
+    };
+}
+export interface ParseResult {
+    content: string;
+    source: "result_contract" | "parser" | "json_extract" | "summary" | "raw_fallback";
+    metadata?: Record<string, unknown>;
+}
+export interface Parser {
+    name: string;
+    preferredBuffers: ("stdoutHead" | "stdoutTail" | "stderrHead" | "stderrTail")[];
+    parse(input: ParseInput): ParseResult | null;
+}

package/dist/parsers/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/parsers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/parsers/types.ts"],"names":[],"mappings":""}

package/dist/parsers/utils.d.ts

@@ -0,0 +1,11 @@
+import type { ParseInput } from "./types.js";
+export declare function joinBuffers(parts: string[]): string;
+export declare function preferredText(input: ParseInput, buffers: Array<keyof Pick<ParseInput, "stdoutHead" | "stdoutTail" | "stderrHead" | "stderrTail">>): string;
+type JsonBlock = {
+    raw: string;
+    value: unknown;
+};
+export declare function findFirstJsonBlock(text: string): JsonBlock | null;
+export declare function extractTextFromContentField(value: unknown): string | null;
+export declare function normalizeNewlines(text: string): string;
+export {};

package/dist/parsers/utils.js

@@ -0,0 +1,116 @@
+export function joinBuffers(parts) {
+    const nonEmpty = parts.filter((p) => p.length > 0);
+    if (nonEmpty.length === 0)
+        return "";
+    let out = nonEmpty[0];
+    for (let i = 1; i < nonEmpty.length; i++) {
+        const next = nonEmpty[i];
+        if (out.endsWith("\n") || next.startsWith("\n")) {
+            out += next;
+        }
+        else {
+            out += "\n" + next;
+        }
+    }
+    return out;
+}
+export function preferredText(input, buffers) {
+    return joinBuffers(buffers.map((b) => input[b]));
+}
+function scanJsonBlock(text, startIndex) {
+    const open = text[startIndex];
+    if (open !== "{" && open !== "[")
+        return null;
+    const stack = [open === "{" ? "}" : "]"];
+    let inString = false;
+    let escaped = false;
+    for (let i = startIndex + 1; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            stack.push("}");
+            continue;
+        }
+        if (ch === "[") {
+            stack.push("]");
+            continue;
+        }
+        if (ch === "}" || ch === "]") {
+            const expected = stack[stack.length - 1];
+            if (expected !== ch)
+                return null;
+            stack.pop();
+            if (stack.length === 0) {
+                return text.slice(startIndex, i + 1);
+            }
+        }
+    }
+    return null;
+}
+export function findFirstJsonBlock(text) {
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch !== "{" && ch !== "[")
+            continue;
+        const raw = scanJsonBlock(text, i);
+        if (raw == null)
+            continue;
+        try {
+            const value = JSON.parse(raw);
+            return { raw, value };
+        }
+        catch {
+            // Keep scanning.
+        }
+    }
+    return null;
+}
+export function extractTextFromContentField(value) {
+    if (value == null || typeof value !== "object")
+        return null;
+    const record = value;
+    if (!("content" in record))
+        return null;
+    const content = record["content"];
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const texts = content
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            if (part && typeof part === "object") {
+                const r = part;
+                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("\n") : null;
+    }
+    return null;
+}
+export function normalizeNewlines(text) {
+    return text.replaceAll("\r\n", "\n");
+}
+//# sourceMappingURL=utils.js.map

package/dist/parsers/utils.js.map

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

package/dist/paths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Startup guard: refuse to run if cwd resolves to filesystem root
+ * unless CLINKX_ALLOWED_ROOTS is explicitly set.
+ *
+ * Call this during server startup.
+ */
+export declare function assertNotRootDir(): void;
+/**
+ * Validate that a given path resolves within one of the allowed roots.
+ *
+ * - Resolves the real path (following symlinks)
+ * - Checks the resolved path starts with an allowed root
+ * - Blocks symlink escapes: realpath must stay within an allow-root
+ *
+ * Throws InvalidParamsError if validation fails.
+ */
+export declare function validatePath(inputPath: string): string;

package/dist/paths.js

@@ -0,0 +1,87 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { InvalidParamsError } from "./errors.js";
+import { logger } from "./logger.js";
+/**
+ * Parse CLINKX_ALLOWED_ROOTS env into an array of resolved absolute paths.
+ * Falls back to process.cwd() when not set.
+ */
+function getAllowedRoots() {
+    const envVal = process.env["CLINKX_ALLOWED_ROOTS"];
+    const raw = envVal != null && envVal.length > 0
+        ? envVal
+            .split(",")
+            .map((r) => r.trim())
+            .filter((r) => r.length > 0)
+        : [process.cwd()];
+    // Resolve through realpath so symlinks (e.g. macOS /var → /private/var)
+    // are consistent with how we resolve validated paths.
+    return raw.map((r) => {
+        try {
+            return fs.realpathSync(path.resolve(r));
+        }
+        catch {
+            return path.resolve(r);
+        }
+    });
+}
+/**
+ * Check whether a resolved path is a filesystem root.
+ * Handles Unix (/) and Windows drive roots (C:\).
+ */
+function isFilesystemRoot(resolved) {
+    // Unix root
+    if (resolved === "/")
+        return true;
+    // Windows drive root: single letter + colon + backslash (or just colon + backslash)
+    if (/^[a-zA-Z]:[/\\]?$/.test(resolved))
+        return true;
+    return false;
+}
+/**
+ * Startup guard: refuse to run if cwd resolves to filesystem root
+ * unless CLINKX_ALLOWED_ROOTS is explicitly set.
+ *
+ * Call this during server startup.
+ */
+export function assertNotRootDir() {
+    const cwd = path.resolve(process.cwd());
+    const hasExplicitRoots = process.env["CLINKX_ALLOWED_ROOTS"] != null &&
+        process.env["CLINKX_ALLOWED_ROOTS"].length > 0;
+    if (isFilesystemRoot(cwd) && !hasExplicitRoots) {
+        throw new Error(`FATAL: cwd resolves to filesystem root (${cwd}). ` +
+            "Running ClinkX from the filesystem root without explicit CLINKX_ALLOWED_ROOTS " +
+            "is refused for safety. Set CLINKX_ALLOWED_ROOTS to an explicit comma-separated " +
+            "list of allowed directories.");
+    }
+    logger.debug({ cwd, hasExplicitRoots }, "root-dir startup guard passed");
+}
+/**
+ * Validate that a given path resolves within one of the allowed roots.
+ *
+ * - Resolves the real path (following symlinks)
+ * - Checks the resolved path starts with an allowed root
+ * - Blocks symlink escapes: realpath must stay within an allow-root
+ *
+ * Throws InvalidParamsError if validation fails.
+ */
+export function validatePath(inputPath) {
+    const roots = getAllowedRoots();
+    let resolved;
+    try {
+        resolved = fs.realpathSync(inputPath);
+    }
+    catch {
+        throw new InvalidParamsError(`Path does not exist or is not accessible: ${inputPath}`);
+    }
+    const withinRoot = roots.some((root) => {
+        const normalizedRoot = root.endsWith(path.sep) ? root : root + path.sep;
+        return resolved === root || resolved.startsWith(normalizedRoot);
+    });
+    if (!withinRoot) {
+        throw new InvalidParamsError(`Path "${inputPath}" (resolved: ${resolved}) is outside allowed roots. ` +
+            `Allowed: ${roots.join(", ")}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=paths.js.map