flex-md 4.7.2 → 4.7.3

package/dist-cjs/__tests__/ofs.test.cjs

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const stringify_js_1 = require("../ofs/stringify.cjs");
+const enricher_js_1 = require("../ofs/enricher.cjs");
+(0, vitest_1.describe)("Instructions Output Format Block Generation", () => {
+    const spec = {
+        description: "Standard report format for technical analysis.",
+        sections: [
+            {
+                name: "Summary",
+                kind: "text",
+                required: true,
+                description: "A brief summary of the topic.",
+                instruction: "Keep it under 3 sentences."
+            },
+            {
+                name: "Key Points",
+                kind: "list",
+                required: false,
+                description: "Important takeaways."
+            }
+        ],
+        emptySectionValue: "N/A"
+    };
+    (0, vitest_1.it)("should stringify an OFS object correctly", () => {
+        const md = (0, stringify_js_1.stringifyOutputFormatSpec)(spec);
+        (0, vitest_1.expect)(md).toContain("## Output format (Markdown)");
+        (0, vitest_1.expect)(md).toContain("Standard report format for technical analysis.");
+        (0, vitest_1.expect)(md).toContain("- Summary — text (required)");
+        (0, vitest_1.expect)(md).toContain("Description: A brief summary of the topic.");
+        (0, vitest_1.expect)(md).toContain("Instruction: Keep it under 3 sentences.");
+        (0, vitest_1.expect)(md).toContain("- Key Points — list (optional)");
+        (0, vitest_1.expect)(md).toContain("Description: Important takeaways.");
+        (0, vitest_1.expect)(md).toContain("If a section is empty, write `N/A`.");
+    });
+    (0, vitest_1.it)("should build markdown guidance (L1) correctly", () => {
+        const guidance = (0, enricher_js_1.buildMarkdownGuidance)(spec, { level: 1 });
+        (0, vitest_1.expect)(guidance).toContain("Include these section headings somewhere");
+        (0, vitest_1.expect)(guidance).toContain("- Summary");
+        (0, vitest_1.expect)(guidance).toContain("Description: A brief summary of the topic.");
+        (0, vitest_1.expect)(guidance).toContain("Instruction: Keep it under 3 sentences.");
+        (0, vitest_1.expect)(guidance).toContain("- Key Points");
+        (0, vitest_1.expect)(guidance).toContain("Description: Important takeaways.");
+    });
+    (0, vitest_1.it)("should build markdown guidance (L3) correctly", () => {
+        const guidance = (0, enricher_js_1.buildMarkdownGuidance)(spec, { level: 3 });
+        (0, vitest_1.expect)(guidance).toContain("Return your entire answer inside a single ```markdown fenced block");
+        (0, vitest_1.expect)(guidance).toContain("- Summary");
+        (0, vitest_1.expect)(guidance).toContain("- Key Points (list)");
+        (0, vitest_1.expect)(guidance).toContain("Do not return JSON");
+    });
+});

package/dist-cjs/__tests__/structural.test.cjs

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_js_1 = require("../index.cjs");
+(0, vitest_1.describe)("Structural Diagnostics", () => {
+    (0, vitest_1.describe)("===key support", () => {
+        (0, vitest_1.it)("should parse ===key as a top-level section", () => {
+            const md = `===skills\nThis is the skills section.\n\n## Subskill\nDetails.`;
+            const outline = (0, index_js_1.buildOutline)(md);
+            (0, vitest_1.expect)(outline.nodes).toHaveLength(1);
+            (0, vitest_1.expect)(outline.nodes[0].title).toBe("skills");
+            (0, vitest_1.expect)(outline.nodes[0].children).toHaveLength(1);
+            (0, vitest_1.expect)(outline.nodes[0].children[0].title).toBe("Subskill");
+        });
+    });
+    (0, vitest_1.describe)("checkConnection", () => {
+        (0, vitest_1.it)("should find a section by name", () => {
+            const md = `# Overview\n## Details\n===skills\nContent.`;
+            const res = (0, index_js_1.checkConnection)(md, "skills");
+            (0, vitest_1.expect)(res.connected).toBe(true);
+            (0, vitest_1.expect)(res.path).toContain("skills");
+        });
+        (0, vitest_1.it)("should fail gracefully for missing sections", () => {
+            const md = `# Overview`;
+            const res = (0, index_js_1.checkConnection)(md, "missing");
+            (0, vitest_1.expect)(res.connected).toBe(false);
+            (0, vitest_1.expect)(res.suggestion).toContain("Overview");
+        });
+    });
+});

package/dist-cjs/__tests__/validate.test.cjs

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const validate_js_1 = require("../validate/validate.cjs");
+const issuesEnvelope_js_1 = require("../ofs/issuesEnvelope.cjs");
+const SPEC = {
+    emptySectionValue: "None",
+    sections: [
+        { name: "Short answer", kind: "text", required: true },
+        { name: "Long answer", kind: "text", required: true },
+        { name: "Reasoning", kind: "ordered_list", required: true },
+        { name: "Assumptions", kind: "list", required: true },
+        { name: "Unknowns", kind: "list", required: true },
+    ],
+};
+function mdL1Good() {
+    return [
+        "## Short answer",
+        "Yes.",
+        "",
+        "## Long answer",
+        "More details.",
+        "",
+        "## Reasoning",
+        "1. First",
+        "2. Second",
+        "",
+        "## Assumptions",
+        "- A",
+        "",
+        "## Unknowns",
+        "- U",
+    ].join("\n");
+}
+(0, vitest_1.describe)("parseIssuesEnvelope()", () => {
+    (0, vitest_1.it)("detects envelope and extracts bullets", () => {
+        const env = [
+            "## Status",
+            "Non-compliant output (cannot be repaired to the required format).",
+            "",
+            "## Issues",
+            "- Missing required section: \"Short answer\"",
+            "",
+            "## Expected",
+            "- Headings ...",
+            "",
+            "## Found",
+            "- Something ...",
+            "",
+            "## How to fix",
+            "- Do X",
+        ].join("\n");
+        const parsed = (0, issuesEnvelope_js_1.parseIssuesEnvelope)(env);
+        (0, vitest_1.expect)(parsed.isIssuesEnvelope).toBe(true);
+        (0, vitest_1.expect)(parsed.sections["issues"].bullets[0]).toContain("Missing required section");
+    });
+});
+(0, vitest_1.describe)("validateMarkdownAgainstOfs()", () => {
+    (0, vitest_1.it)("L0 accepts anything", () => {
+        const r = (0, validate_js_1.validateMarkdownAgainstOfs)("whatever", SPEC, 0);
+        (0, vitest_1.expect)(r.ok).toBe(true);
+    });
+    (0, vitest_1.it)("L1 fails when required section missing", () => {
+        const md = [
+            "## Short answer",
+            "Yes.",
+            "",
+            "## Reasoning",
+            "1. A",
+        ].join("\n");
+        const r = (0, validate_js_1.validateMarkdownAgainstOfs)(md, SPEC, 1);
+        (0, vitest_1.expect)(r.ok).toBe(false);
+        (0, vitest_1.expect)(r.issues.some(i => i.code === "MISSING_SECTION")).toBe(true);
+    });
+    (0, vitest_1.it)("L2 requires a single fenced markdown block", () => {
+        const r = (0, validate_js_1.validateMarkdownAgainstOfs)(mdL1Good(), SPEC, 2);
+        (0, vitest_1.expect)(r.ok).toBe(false);
+        (0, vitest_1.expect)(r.issues.some(i => i.code === "CONTAINER_MISSING")).toBe(true);
+    });
+    (0, vitest_1.it)("L2 passes with one fence containing valid L1", () => {
+        const md = ["```markdown", mdL1Good(), "```"].join("\n");
+        const r = (0, validate_js_1.validateMarkdownAgainstOfs)(md, SPEC, 2);
+        (0, vitest_1.expect)(r.ok).toBe(true);
+    });
+    (0, vitest_1.it)("L3 enforces section kinds (Reasoning must be ordered list)", () => {
+        const bad = [
+            "```markdown",
+            [
+                "## Short answer",
+                "Yes",
+                "",
+                "## Long answer",
+                "Details",
+                "",
+                "## Reasoning",
+                "- bullet but should be ordered",
+                "",
+                "## Assumptions",
+                "- A",
+                "",
+                "## Unknowns",
+                "- U",
+            ].join("\n"),
+            "```",
+        ].join("\n");
+        const r = (0, validate_js_1.validateMarkdownAgainstOfs)(bad, SPEC, 3);
+        (0, vitest_1.expect)(r.ok).toBe(false);
+        (0, vitest_1.expect)(r.issues.some(i => i.code === "WRONG_SECTION_KIND")).toBe(true);
+    });
+});

package/dist-cjs/cli/index.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = require("path");
+const index_js_1 = require("../index.cjs");
+const [, , command, ...args] = process.argv;
+async function main() {
+    if (!command || command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    try {
+        switch (command) {
+            case "check":
+                await handleCheck(args);
+                break;
+            case "diagnose":
+                await handleDiagnose(args);
+                break;
+            case "create":
+                await handleCreate(args);
+                break;
+            case "sync":
+                await handleSync(args);
+                break;
+            default:
+                console.error(`Unknown command: ${command}`);
+                printHelp();
+                process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`
+Flex-MD CLI v3.2.0
+
+Usage:
+  flex-md <command> [options]
+
+Commands:
+  check <file> [--level L2]    Check compliance of a markdown file.
+  diagnose <file> <key>        Diagnose if a specific key/section is connected.
+  create <file> <key>          Create a new section (folder/file simulation).
+  sync <source> <target>       Sync content from source to target.
+
+Options:
+  --help, -h                  Show this help message.
+    `);
+}
+async function handleCheck(args) {
+    const file = args[0];
+    if (!file)
+        throw new Error("Missing file argument.");
+    const level = (args.includes("--level") ? args[args.indexOf("--level") + 1] : "L2");
+    const content = (0, fs_1.readFileSync)((0, path_1.resolve)(file), "utf-8");
+    const result = await (0, index_js_1.checkCompliance)(content, level);
+    if (result.meetsCompliance) {
+        console.log("✅ Content meets compliance.");
+    }
+    else {
+        console.log("❌ Content does not meet compliance.");
+        result.issues.forEach(i => console.log(`  - [${i.severity}] ${i.description}`));
+        console.log("\nSuggestions:");
+        result.suggestions.forEach(s => console.log(`  - ${s}`));
+    }
+}
+async function handleDiagnose(args) {
+    const file = args[0];
+    const key = args[1];
+    if (!file || !key)
+        throw new Error("Usage: flex-md diagnose <file> <key>");
+    if (!(0, fs_1.existsSync)(file))
+        throw new Error(`File not found: ${file}`);
+    const content = (0, fs_1.readFileSync)((0, path_1.resolve)(file), "utf-8");
+    const result = (0, index_js_1.checkConnection)(content, key);
+    if (result.connected) {
+        console.log(`✅ Key "${key}" found at path: ${result.path?.join(" -> ")}`);
+    }
+    else {
+        console.log(`❌ Key "${key}" not connected.`);
+        console.log(`Suggestion: ${result.suggestion}`);
+    }
+}
+async function handleCreate(args) {
+    const file = args[0];
+    const key = args[1];
+    if (!file || !key)
+        throw new Error("Usage: flex-md create <file> <key>");
+    const content = (0, fs_1.existsSync)(file) ? (0, fs_1.readFileSync)(file, "utf-8") : "";
+    const newContent = content + `\n\n## ${key}\n\n[Content for ${key}]\n`;
+    (0, fs_1.writeFileSync)(file, newContent);
+    console.log(`✅ Section "${key}" created in ${file}`);
+}
+async function handleSync(args) {
+    const source = args[0];
+    const target = args[1];
+    if (!source || !target)
+        throw new Error("Usage: flex-md sync <source> <target>");
+    if (!(0, fs_1.existsSync)(source))
+        throw new Error(`Source file not found: ${source}`);
+    const content = (0, fs_1.readFileSync)(source, "utf-8");
+    (0, fs_1.writeFileSync)(target, content);
+    console.log(`✅ Content synced from ${source} to ${target}`);
+}
+main();

package/dist-cjs/detect/json/detectIntent.cjs

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectJsonIntent = detectJsonIntent;
+const HARD_PATTERNS = [
+    /\breturn\s+only\s+json\b/i,
+    /\boutput\s+only\s+json\b/i,
+    /\bvalid\s+json\s+(object|array)\b/i,
+    /\bno\s+(prose|text|markdown)\b/i,
+    /\bdo\s+not\s+output\s+anything\s+else\b/i,
+];
+const SOFT_PATTERNS = [
+    /\binclude\s+json\b/i,
+    /\bjson\s+preferred\b/i,
+    /\badd\s+a\s+json\b/i,
+    /\bjson\s+format\b/i,
+];
+const SCHEMA_PATTERNS = [
+    /\bjson\s+schema\b/i,
+    /\bschema\b.*\bjson\b/i,
+    /\bajv\b/i,
+    /\bzod\b/i,
+    /\bopenapi\b/i,
+];
+const TOOLING_PATTERNS = [
+    /\bfunction\s+calling\b/i,
+    /\btools?\b/i,
+    /\bresponse_format\b/i,
+    /\btool\s+call\b/i,
+    /\barguments\b.*\bjson\b/i,
+];
+function detectJsonIntent(text) {
+    const signals = [];
+    const add = (rx, strength, idx, len) => {
+        signals.push({
+            type: "pattern",
+            value: rx.source,
+            strength,
+            start: idx,
+            end: idx != null && len != null ? idx + len : undefined,
+        });
+    };
+    const scan = (patterns, strength) => {
+        for (const base of patterns) {
+            const rx = new RegExp(base.source, base.flags.includes("g") ? base.flags : base.flags + "g");
+            rx.lastIndex = 0;
+            let m;
+            while ((m = rx.exec(text)) !== null) {
+                add(base, strength, m.index, m[0]?.length ?? 0);
+                if (m[0]?.length === 0)
+                    rx.lastIndex++;
+            }
+        }
+    };
+    scan(HARD_PATTERNS, "hard");
+    scan(TOOLING_PATTERNS, "soft");
+    scan(SCHEMA_PATTERNS, "soft");
+    scan(SOFT_PATTERNS, "soft");
+    const hasHard = signals.some(s => s.strength === "hard");
+    const hasSchema = signals.some(s => SCHEMA_PATTERNS.some(rx => rx.source === s.value));
+    const hasTooling = signals.some(s => TOOLING_PATTERNS.some(rx => rx.source === s.value));
+    const hasSoft = signals.some(s => s.strength === "soft");
+    let intent = "none";
+    if (hasHard)
+        intent = "hard";
+    else if (hasSchema)
+        intent = "schema";
+    else if (hasTooling)
+        intent = "tooling";
+    else if (hasSoft)
+        intent = "soft";
+    const confidence = scoreConfidence(intent, signals);
+    return { intent, signals, confidence };
+}
+function scoreConfidence(intent, signals) {
+    if (intent === "none")
+        return signals.length ? 0.2 : 0.0;
+    const hard = signals.filter(s => s.strength === "hard").length;
+    const soft = signals.filter(s => s.strength === "soft").length;
+    if (intent === "hard")
+        return Math.min(1, 0.7 + hard * 0.15);
+    return Math.min(1, 0.4 + soft * 0.1);
+}

package/dist-cjs/detect/json/detectMarkdown.cjs

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * Helpers for "framed vs frameless" Markdown handling before Flex-MD.
+ *
+ * Goals:
+ * 1) Detect framed markdown (single fenced block) and extract its inner content.
+ * 2) If NOT markdown-ish, force-wrap into a minimal markdown shape so Flex-MD can still parse.
+ *
+ * Notes:
+ * - This is heuristic by design; tune thresholds as you learn your data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectMarkdown = detectMarkdown;
+exports.stripSingleFence = stripSingleFence;
+exports.forceWrapAsMarkdown = forceWrapAsMarkdown;
+exports.normalizeForFlexMd = normalizeForFlexMd;
+const logger_js_1 = require("../../logger.cjs");
+const SINGLE_FENCE_BLOCK_RE = /^```([a-zA-Z0-9_-]+)?([^\n]*)\n([\s\S]*?)\n```$/;
+const FENCE_OPEN_RE = /(^|\n)```/g;
+function detectMarkdown(text) {
+    logger_js_1.logger.debug("Starting markdown detection", {
+        inputType: typeof text,
+        inputLength: typeof text === "string" ? text.length : JSON.stringify(text ?? "").length
+    });
+    const reasons = [];
+    const raw = typeof text === "string" ? text : JSON.stringify(text ?? "");
+    const s = raw.replace(/\r\n/g, "\n");
+    logger_js_1.logger.verbose("Input normalized for processing", {
+        originalType: typeof text,
+        normalizedLength: s.length,
+        hasNewlines: s.includes('\n')
+    });
+    const codeFences = [...s.matchAll(FENCE_OPEN_RE)].length;
+    logger_js_1.logger.debug("Code fence analysis", {
+        totalFences: codeFences,
+        fenceRegex: FENCE_OPEN_RE.source
+    });
+    // Framed detection (single fenced block)
+    const m = s.match(SINGLE_FENCE_BLOCK_RE);
+    const isFramed = !!m && codeFences === 2;
+    const frameLanguage = isFramed ? (m?.[1] ?? null) : null;
+    logger_js_1.logger.debug("Framed markdown detection", {
+        regexMatch: !!m,
+        expectedFences: 2,
+        actualFences: codeFences,
+        isFramed,
+        frameLanguage,
+        regexGroups: m ? {
+            fullMatch: m[0],
+            language: m[1],
+            content: m[3]?.substring(0, 100) + (m[3]?.length > 100 ? '...' : '')
+        } : null
+    });
+    if (isFramed) {
+        reasons.push("Single fenced code block detected (framed payload).");
+        logger_js_1.logger.info("Detected framed markdown", { language: frameLanguage });
+    }
+    else if (codeFences > 2) {
+        reasons.push("Multiple fenced code blocks detected.");
+        logger_js_1.logger.debug("Multiple fences detected, not treating as single framed block", { fenceCount: codeFences });
+    }
+    else if (codeFences === 1) {
+        reasons.push("Single fence marker found but not properly framed.");
+        logger_js_1.logger.debug("Single fence found but regex didn't match", {
+            regex: SINGLE_FENCE_BLOCK_RE.source,
+            hasMatch: !!m
+        });
+    }
+    else {
+        logger_js_1.logger.debug("No fence markers detected");
+    }
+    const lines = s.split("\n");
+    logger_js_1.logger.verbose("Line-by-line analysis started", { totalLines: lines.length });
+    const atxHeadings = lines.filter((l) => /^#{1,6}\s+\S/.test(l.trim())).length;
+    let setextHeadings = 0;
+    for (let i = 0; i < lines.length - 1; i++) {
+        const cur = lines[i].trim();
+        const nxt = lines[i + 1].trim();
+        if (cur.length > 0 && (/^={2,}$/.test(nxt) || /^-{2,}$/.test(nxt)))
+            setextHeadings++;
+    }
+    const headings = atxHeadings + setextHeadings;
+    const unorderedListLines = lines.filter((l) => /^\s*[-*+]\s+\S/.test(l)).length;
+    const orderedListLines = lines.filter((l) => /^\s*\d{1,3}([.)])\s+\S/.test(l)).length;
+    const tableRows = lines.filter((l) => {
+        const t = l.trim();
+        if (!t.startsWith("|") || t.length < 3)
+            return false;
+        const pipeCount = (t.match(/\|/g) ?? []).length;
+        return pipeCount >= 2;
+    }).length;
+    const inlineCodeSpans = (s.match(/`[^`\n]+`/g) ?? []).length;
+    const mdLinks = (s.match(/\[[^\]]+\]\([^)]+\)/g) ?? []).length;
+    const emphasisTokens = (s.match(/\*\*[^*\n]+\*\*/g) ?? []).length +
+        (s.match(/__[^_\n]+__/g) ?? []).length +
+        (s.match(/(^|[^*])\*[^*\n]+\*([^*]|$)/g) ?? []).length +
+        (s.match(/(^|[^_])_[^_\n]+_([^_]|$)/g) ?? []).length;
+    logger_js_1.logger.debug("Markdown structure analysis", {
+        atxHeadings,
+        setextHeadings,
+        totalHeadings: headings,
+        unorderedListLines,
+        orderedListLines,
+        tableRows,
+        inlineCodeSpans,
+        mdLinks,
+        emphasisTokens
+    });
+    // Heuristic decision rules
+    const hasList = unorderedListLines + orderedListLines >= 2;
+    const hasTable = tableRows >= 2;
+    const hasOtherSignals = inlineCodeSpans + mdLinks + emphasisTokens >= 2;
+    logger_js_1.logger.debug("Heuristic analysis", {
+        hasList,
+        hasTable,
+        hasOtherSignals,
+        listThreshold: 2,
+        tableThreshold: 2,
+        otherSignalsThreshold: 2
+    });
+    let isMarkdownLikely = false;
+    if (isFramed) {
+        isMarkdownLikely = true;
+        logger_js_1.logger.debug("Markdown likelihood determined: framed content is always considered markdown");
+    }
+    else if (headings >= 2) {
+        isMarkdownLikely = true;
+        reasons.push(`Detected ${headings} markdown heading(s) (>=2).`);
+        logger_js_1.logger.debug("Markdown likelihood: sufficient headings detected", { headingCount: headings });
+    }
+    else if (headings >= 1 && (hasList || hasTable)) {
+        isMarkdownLikely = true;
+        reasons.push(`Detected heading(s) plus ${hasList ? "list" : "table"} structure.`);
+        logger_js_1.logger.debug("Markdown likelihood: heading plus structural element", {
+            hasHeading: headings >= 1,
+            hasList,
+            hasTable
+        });
+    }
+    else if ((hasList && hasTable) || (hasTable && hasOtherSignals) || (hasList && hasOtherSignals)) {
+        isMarkdownLikely = true;
+        reasons.push("Detected multiple markdown structural signals (lists/tables/links/code/emphasis).");
+        logger_js_1.logger.debug("Markdown likelihood: multiple structural signals", {
+            listAndTable: hasList && hasTable,
+            tableAndOther: hasTable && hasOtherSignals,
+            listAndOther: hasList && hasOtherSignals
+        });
+    }
+    else {
+        reasons.push("Insufficient markdown structure signals; treating as plain text.");
+        logger_js_1.logger.debug("Markdown likelihood: insufficient signals, treating as plain text", {
+            headings,
+            hasList,
+            hasTable,
+            hasOtherSignals
+        });
+    }
+    if (/^\s*#{1,6}\s+\S/.test(lines[0] ?? "")) {
+        reasons.push("Text starts with an ATX heading (#...).");
+        isMarkdownLikely = true;
+        logger_js_1.logger.debug("Additional check: starts with heading, upgrading to markdown");
+    }
+    return {
+        isMarkdownLikely,
+        isFramed,
+        frameLanguage,
+        reasons,
+        stats: {
+            headings,
+            atxHeadings,
+            setextHeadings,
+            unorderedListLines,
+            orderedListLines,
+            tableRows,
+            codeFences,
+            inlineCodeSpans,
+            mdLinks,
+            emphasisTokens,
+        },
+    };
+}
+/**
+ * If the entire payload is a single fenced block, return its inner content.
+ * Otherwise return the original text.
+ *
+ * - Also handles ```md / ```markdown / ```json etc.
+ */
+function stripSingleFence(input) {
+    const s = input.replace(/\r\n/g, "\n").trim();
+    const fenceCount = [...s.matchAll(FENCE_OPEN_RE)].length;
+    if (fenceCount !== 2) {
+        return { stripped: input, wasFramed: false, language: null };
+    }
+    const m = s.match(SINGLE_FENCE_BLOCK_RE);
+    if (!m)
+        return { stripped: input, wasFramed: false, language: null };
+    const lang = (m[1] ?? null);
+    const inner = (m[3] ?? "").trim();
+    return { stripped: inner, wasFramed: true, language: lang };
+}
+/**
+ * Force-wrap non-markdown text into a minimal heading-based markdown document.
+ * This helps Flex-MD / nx-md-parser operate even when the model returns plain text.
+ *
+ * Choose a heading that exists in your OFS to maximize alignment.
+ * Default: "Full Answer" (common sink section).
+ */
+function forceWrapAsMarkdown(plainText, opts) {
+    const heading = opts?.heading ?? "Full Answer";
+    const level = opts?.level ?? 3;
+    const hashes = "#".repeat(level);
+    const raw = plainText.replace(/\r\n/g, "\n");
+    const body = opts?.preserveLeadingWhitespace ? raw : raw.trim();
+    // If empty, keep it explicit.
+    const safeBody = body.length ? body : "None";
+    return `${hashes} ${heading}\n${safeBody}\n`;
+}
+/**
+ * End-to-end "normalize input for Flex-MD" helper:
+ * - If framed: strip the fence (so Flex-MD sees pure markdown)
+ * - Else: if markdown-likely: keep as-is
+ * - Else: wrap as markdown under a chosen heading
+ */
+function normalizeForFlexMd(input, opts) {
+    logger_js_1.logger.info("Starting Flex-MD normalization", {
+        inputType: typeof input,
+        inputLength: typeof input === "string" ? input.length : JSON.stringify(input ?? "").length,
+        options: opts
+    });
+    const raw = typeof input === "string" ? input : JSON.stringify(input ?? "");
+    const detection = detectMarkdown(raw);
+    logger_js_1.logger.debug("Detection completed", {
+        isFramed: detection.isFramed,
+        isMarkdownLikely: detection.isMarkdownLikely,
+        frameLanguage: detection.frameLanguage,
+        reasons: detection.reasons
+    });
+    // 1) Strip if framed
+    const { stripped, wasFramed, language } = stripSingleFence(raw);
+    logger_js_1.logger.debug("Strip fence check", {
+        wasFramed,
+        language,
+        strippedLength: stripped.length,
+        originalLength: raw.length
+    });
+    if (wasFramed) {
+        logger_js_1.logger.info("Normalization: stripped framed markdown", {
+            language,
+            contentLength: stripped.length
+        });
+        return {
+            normalizedText: stripped,
+            detection,
+            wasStripped: true,
+            stripLanguage: language,
+            wasWrapped: false,
+        };
+    }
+    // 2) Keep if markdown-likely
+    if (detection.isMarkdownLikely) {
+        logger_js_1.logger.info("Normalization: keeping as-is (markdown-likely)", {
+            reasons: detection.reasons
+        });
+        return {
+            normalizedText: raw,
+            detection,
+            wasStripped: false,
+            stripLanguage: null,
+            wasWrapped: false,
+        };
+    }
+    // 3) Wrap if not markdown-likely
+    const fallbackHeading = opts?.fallbackHeading ?? "Full Answer";
+    const fallbackLevel = opts?.fallbackHeadingLevel ?? 3;
+    logger_js_1.logger.info("Normalization: wrapping as markdown", {
+        fallbackHeading,
+        fallbackLevel,
+        reasons: detection.reasons
+    });
+    const wrapped = forceWrapAsMarkdown(raw, {
+        heading: fallbackHeading,
+        level: fallbackLevel,
+    });
+    logger_js_1.logger.debug("Wrapping completed", {
+        wrappedLength: wrapped.length,
+        originalLength: raw.length
+    });
+    return {
+        normalizedText: wrapped,
+        detection,
+        wasStripped: false,
+        stripLanguage: null,
+        wasWrapped: true,
+    };
+}
+/**
+ * Example integration with Flex-MD:
+ *
+ * import { parseOutputFormatSpec, transformWithOfs } from 'flex-md';
+ *
+ * const spec = parseOutputFormatSpec(ofsMarkdown);
+ * const prep = normalizeForFlexMd(llmText, { fallbackHeading: "Full Answer" });
+ * const out = transformWithOfs(prep.normalizedText, spec);
+ */