flex-md 3.1.0 → 3.5.0

package/README.md

@@ -9,8 +9,8 @@ Version 3.0 introduces the **Detect-Repair-Enforce** pipeline, ensuring LLM resp
 - **Standard Markdown**: No proprietary tags. Pure headings, lists, and tables.
 - **Strictness Levels (L0–L3)**: From loose guidance to rigid structural enforcement.
 - **Deterministic Repair**: Auto-fixes misformatted LLM output (merged fences, missing headings, format conversion).
+- **Instructions Output Format Guidance**: Generate formal "Instructions Blocks" for LLM prompts directly from spec objects.
 - **Issues Envelope**: A structured failure format for when repairs fail, allowing safe fallbacks.
-- **Tax-Aware Prompts**: Generates minimal, relevant instructions to save tokens.
 
 ## Installation
 
@@ -61,6 +61,35 @@ if (result.ok) {
 }
 ```
 
+### 4. Dynamic Instructions Output Format Blocks
+
+You can also define your spec as a plain JavaScript object and generate the formal "Instructions Block" for your LLM prompts.
+
+```typescript
+import { stringifyOutputFormatSpec } from 'flex-md';
+
+const spec = {
+  description: "Standard report format for technical analysis.",
+  sections: [
+    {
+      name: "Summary",
+      kind: "text",
+      required: true,
+      description: "A brief summary of the topic."
+    },
+    {
+      name: "Key Points",
+      kind: "list",
+      required: false,
+      instruction: "Include at least 3 bullet points."
+    }
+  ]
+};
+
+const instructionsBlock = stringifyOutputFormatSpec(spec);
+// Output will include the ## Output format (Markdown) header, descriptions, and instructions.
+```
+
 ## Strictness Levels
 
 | Level | Goal | Guidance | Enforcement |

package/dist/__tests__/diagnostics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/diagnostics.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { checkCompliance, hasFlexMdContract, enrichInstructionsWithFlexMd, validateFormat } from "../index.js";
+describe("Diagnostics", () => {
+    describe("checkCompliance", () => {
+        it("should return meetsCompliance: true for L0 if Markdown is mentioned", async () => {
+            const res = await checkCompliance("Reply in Markdown.", "L0");
+            expect(res.meetsCompliance).toBe(true);
+            expect(res.issues).toHaveLength(0);
+        });
+        it("should return issues for L2 if container is missing", async () => {
+            const res = await checkCompliance("Reply in Markdown. Include headings.", "L2");
+            expect(res.meetsCompliance).toBe(false);
+            expect(res.issues.some(i => i.type === "missing-container")).toBe(true);
+        });
+        it("should return false for hasFlexMdContract if requirements not met", async () => {
+            const ok = await hasFlexMdContract("Hello", "L0");
+            expect(ok).toBe(false);
+        });
+    });
+    describe("enrichInstructionsWithFlexMd", () => {
+        it("should append guidance to existing instructions", async () => {
+            const res = await enrichInstructionsWithFlexMd("Do a good job.", "L0");
+            expect(res.enriched).toContain("Do a good job.");
+            expect(res.enriched).toContain("Reply in Markdown.");
+            expect(res.changes).toHaveLength(1);
+            expect(res.metadata?.guidanceAdded).toBe(true);
+        });
+        it("should track container addition for L2", async () => {
+            const res = await enrichInstructionsWithFlexMd("Do a good job.", "L2");
+            expect(res.changes.some(c => c.type === "added-container")).toBe(true);
+            expect(res.metadata?.containerAdded).toBe(true);
+        });
+    });
+    describe("validateFormat", () => {
+        it("should validate a correct flex-md OFS", async () => {
+            const ofs = `## Output format\n- Summary — prose\n- Actions — list`;
+            const res = await validateFormat(ofs);
+            expect(res.valid).toBe(true);
+            expect(res.metadata?.sectionCount).toBe(2);
+        });
+        it("should return errors for missing heading", async () => {
+            const ofs = `- Summary — prose`;
+            const res = await validateFormat(ofs);
+            expect(res.valid).toBe(false);
+            expect(res.issues.some(i => i.type === "missing-heading")).toBe(true);
+        });
+        it("should validate JSON schema", async () => {
+            const schema = `{"type": "object"}`;
+            const res = await validateFormat(schema, "json-schema");
+            expect(res.valid).toBe(true);
+        });
+        it("should fail on invalid JSON schema", async () => {
+            const schema = `{"type": "object"`;
+            const res = await validateFormat(schema, "json-schema");
+            expect(res.valid).toBe(false);
+            expect(res.issues[0].type).toBe("syntax-error");
+        });
+    });
+});

package/dist/__tests__/ofs.test.js

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { stringifyOutputFormatSpec } from "../ofs/stringify.js";
 import { buildMarkdownGuidance } from "../ofs/enricher.js";
-describe("OFS Object-to-Prompt Flow", () => {
+describe("Instructions Output Format Block Generation", () => {
     const spec = {
         description: "Standard report format for technical analysis.",
         sections: [

package/dist/__tests__/structural.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/structural.test.js

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

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import { checkCompliance, checkConnection } from "../index.js";
+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 = readFileSync(resolve(file), "utf-8");
+    const result = await 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 (!existsSync(file))
+        throw new Error(`File not found: ${file}`);
+    const content = readFileSync(resolve(file), "utf-8");
+    const result = 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 = existsSync(file) ? readFileSync(file, "utf-8") : "";
+    const newContent = content + `\n\n## ${key}\n\n[Content for ${key}]\n`;
+    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 (!existsSync(source))
+        throw new Error(`Source file not found: ${source}`);
+    const content = readFileSync(source, "utf-8");
+    writeFileSync(target, content);
+    console.log(`✅ Content synced from ${source} to ${target}`);
+}
+main();

package/dist/index.d.ts

@@ -1,10 +1,13 @@
 export * from "./types.js";
 export * from "./strictness/types.js";
 export * from "./md/parse.js";
-export { parseOutputFormatSpec } from "./ofs/parser.js";
+export { buildOutline } from "./md/outline.js";
+export { parseOutputFormatSpec, validateFormat } from "./ofs/parser.js";
 export { stringifyOutputFormatSpec } from "./ofs/stringify.js";
-export { buildMarkdownGuidance, enrichInstructions } from "./ofs/enricher.js";
+export { buildMarkdownGuidance, enrichInstructions, enrichInstructionsWithFlexMd } from "./ofs/enricher.js";
 export { validateMarkdownAgainstOfs } from "./validate/validate.js";
+export { checkCompliance, hasFlexMdContract } from "./validate/compliance.js";
+export { checkConnection } from "./validate/connection.js";
 export { extractFromMarkdown } from "./extract/extract.js";
 export { processResponseMarkdown } from "./strictness/processor.js";
 export { parseIssuesEnvelope, buildIssuesEnvelope, buildIssuesEnvelopeAuto } from "./ofs/issuesEnvelope.js";

package/dist/index.js

@@ -3,12 +3,15 @@ export * from "./types.js";
 export * from "./strictness/types.js";
 // Shared MD Parsing
 export * from "./md/parse.js";
+export { buildOutline } from "./md/outline.js";
 // Output Format Spec (OFS)
-export { parseOutputFormatSpec } from "./ofs/parser.js";
+export { parseOutputFormatSpec, validateFormat } from "./ofs/parser.js";
 export { stringifyOutputFormatSpec } from "./ofs/stringify.js";
-export { buildMarkdownGuidance, enrichInstructions } from "./ofs/enricher.js";
+export { buildMarkdownGuidance, enrichInstructions, enrichInstructionsWithFlexMd } from "./ofs/enricher.js";
 // Validation & Extraction
 export { validateMarkdownAgainstOfs } from "./validate/validate.js";
+export { checkCompliance, hasFlexMdContract } from "./validate/compliance.js";
+export { checkConnection } from "./validate/connection.js";
 export { extractFromMarkdown } from "./extract/extract.js";
 // Processor & Fallback
 export { processResponseMarkdown } from "./strictness/processor.js";

package/dist/md/outline.d.ts

@@ -1,6 +1,9 @@
-import type { MdOutline } from "../types.js";
+import { MdOutline } from "../types.js";
 /**
- * Builds a nested outline tree from Markdown headings.
- * Supports any heading level and captures content between headings.
+ * Builds a nested tree of headings (outline) from Markdown text.
  */
 export declare function buildOutline(md: string): MdOutline;
+/**
+ * Slugifies a string into an internal key.
+ */
+export declare function slugify(text: string): string;

package/dist/md/outline.js

@@ -1,67 +1,45 @@
+import { parseHeadingsAndSections } from "./parse.js";
 /**
- * Builds a nested outline tree from Markdown headings.
- * Supports any heading level and captures content between headings.
+ * Builds a nested tree of headings (outline) from Markdown text.
  */
 export function buildOutline(md) {
-    const lines = md.split("\n");
-    const headings = [];
-    for (let i = 0; i < lines.length; i++) {
-        const m = (lines[i] ?? "").match(/^(#{1,6})\s+(.+?)\s*$/);
-        if (m) {
-            headings.push({ idx: i, level: m[1].length, title: cleanTitle(m[2]) });
-        }
-    }
-    if (!headings.length) {
-        return { type: "md_outline", nodes: [] };
-    }
-    const nodes = [];
+    const sections = parseHeadingsAndSections(md);
+    const roots = [];
     const stack = [];
-    for (let h = 0; h < headings.length; h++) {
-        const cur = headings[h];
-        const next = headings[h + 1];
-        const contentStart = cur.idx + 1;
-        const contentEnd = next ? next.idx : lines.length;
-        const content_md = lines.slice(contentStart, contentEnd).join("\n").trimEnd() + "\n";
+    for (const s of sections) {
+        const h = s.heading;
         const node = {
-            title: cur.title,
-            level: cur.level,
-            key: "",
-            content_md,
+            title: h.name,
+            level: h.level,
+            key: h.norm,
+            content_md: s.body,
             children: []
         };
-        while (stack.length && stack[stack.length - 1].level >= node.level) {
+        // Pop from stack until we find a parent (level < node.level)
+        while (stack.length > 0 && stack[stack.length - 1].level >= node.level) {
             stack.pop();
         }
-        if (!stack.length) {
-            nodes.push(node);
+        if (stack.length === 0) {
+            roots.push(node);
         }
         else {
             stack[stack.length - 1].children.push(node);
         }
         stack.push(node);
     }
-    assignKeys(nodes);
-    return { type: "md_outline", nodes };
-}
-function cleanTitle(t) {
-    return t.trim().replace(/[:\-–—]\s*$/, "").trim();
-}
-function slugify(t) {
-    return t.toLowerCase()
-        .replace(/[:\-–—]+$/g, "")
-        .replace(/\s+/g, "_")
-        .replace(/[^a-z0-9_]/g, "")
-        .replace(/_+/g, "_")
-        .replace(/^_+|_+$/g, "");
-}
-function assignKeys(nodes) {
-    const seen = new Map();
-    const visit = (n) => {
-        const base = slugify(n.title) || "section";
-        const count = (seen.get(base) ?? 0) + 1;
-        seen.set(base, count);
-        n.key = count === 1 ? base : `${base}__${count}`;
-        n.children.forEach(visit);
+    return {
+        type: "md_outline",
+        nodes: roots
     };
-    nodes.forEach(visit);
+}
+/**
+ * Slugifies a string into an internal key.
+ */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/[\s_-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
 }

package/dist/md/parse.js

@@ -28,17 +28,28 @@ export function extractFencedBlocks(text) {
     return blocks;
 }
 export function parseHeadingsAndSections(md) {
-    const rx = /^(#{1,6})\s+(.+?)\s*$/gm;
+    // Standard headings #... and alternative ===key
+    const rx = /^((?:#{1,6})\s+(.+?)\s*|===(.+?)\s*)$/gm;
     const headings = [];
     let m;
     while ((m = rx.exec(md)) !== null) {
-        const hashes = m[1] ?? "";
-        const name = (m[2] ?? "").trim();
+        const full = m[1] ?? "";
+        let level;
+        let name;
+        if (full.startsWith("===")) {
+            level = 1; // Treat ===key as a top-level heading
+            name = (m[3] ?? "").trim();
+        }
+        else {
+            const hashes = (full.match(/^#+/) ?? [""])[0];
+            level = hashes.length;
+            name = (m[2] ?? "").trim();
+        }
         const raw = m[0] ?? "";
         const start = m.index;
         const end = start + raw.length;
         headings.push({
-            level: hashes.length,
+            level,
             raw,
             name,
             norm: normalizeName(name),

package/dist/ofs/enricher.d.ts

@@ -1,4 +1,4 @@
-import { OutputFormatSpec } from "../types.js";
+import { OutputFormatSpec, EnhancementResult } from "../types.js";
 import { StrictnessOptions } from "../strictness/types.js";
 /**
  * Generates Markdown guidance instructions for the LLM based on the OFS and contract level.
@@ -14,3 +14,8 @@ export declare function buildMarkdownGuidance(spec: OutputFormatSpec, strict: St
  * @deprecated Use buildMarkdownGuidance
  */
 export declare function enrichInstructions(spec: OutputFormatSpec, strict: StrictnessOptions): string;
+/**
+ * Enrich instructions with flex-md compliance guidance.
+ * Returns detailed information about what was changed.
+ */
+export declare function enrichInstructionsWithFlexMd(instructions: string, strictnessLevel: "L0" | "L1" | "L2" | "L3", spec?: OutputFormatSpec): Promise<EnhancementResult>;

package/dist/ofs/enricher.js

@@ -83,3 +83,64 @@ export function buildMarkdownGuidance(spec, strict, opts) {
 export function enrichInstructions(spec, strict) {
     return buildMarkdownGuidance(spec, strict);
 }
+/**
+ * Enrich instructions with flex-md compliance guidance.
+ * Returns detailed information about what was changed.
+ */
+export async function enrichInstructionsWithFlexMd(instructions, strictnessLevel, spec // Optional spec, if provided will include section guidance
+) {
+    const originalLength = instructions.length;
+    const level = parseInt(strictnessLevel.slice(1));
+    // Default spec if none provided (minimal)
+    const effectiveSpec = spec ?? { sections: [] };
+    const guidance = buildMarkdownGuidance(effectiveSpec, { level });
+    // Check if guidance is already present (simple check)
+    if (instructions.includes(guidance)) {
+        return {
+            enriched: instructions,
+            changes: [],
+            originalLength,
+            enhancedLength: originalLength,
+            metadata: {
+                sectionsAdded: 0,
+                containerAdded: false,
+                guidanceAdded: false
+            }
+        };
+    }
+    const separator = instructions.trim().length > 0 ? "\n\n" : "";
+    const enriched = instructions.trim() + separator + guidance;
+    const enhancedLength = enriched.length;
+    const changes = [
+        {
+            type: "added-guidance",
+            description: `Added Flex-MD ${strictnessLevel} compliance guidance.`,
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            },
+            content: guidance
+        }
+    ];
+    if (level >= 2) {
+        changes.push({
+            type: "added-container",
+            description: "Added requirement for a fenced container block.",
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            }
+        });
+    }
+    return {
+        enriched,
+        changes,
+        originalLength,
+        enhancedLength,
+        metadata: {
+            sectionsAdded: effectiveSpec.sections.length,
+            containerAdded: level >= 2,
+            guidanceAdded: true
+        }
+    };
+}

package/dist/ofs/parser.d.ts

@@ -1,4 +1,9 @@
-import type { OutputFormatSpec } from "../types.js";
+import type { OutputFormatSpec, FormatValidationResult } from "../types.js";
+/**
+ * Validate a format specification.
+ * Returns detailed validation results.
+ */
+export declare function validateFormat(formatSpec: string, formatType?: "flex-md" | "json-schema"): Promise<FormatValidationResult>;
 /**
  * Parse an Output Format Spec block from Markdown.
  */

package/dist/ofs/parser.js

@@ -1,3 +1,73 @@
+/**
+ * Validate a format specification.
+ * Returns detailed validation results.
+ */
+export async function validateFormat(formatSpec, formatType = "flex-md") {
+    const issues = [];
+    const suggestions = [];
+    if (formatType === "json-schema") {
+        try {
+            JSON.parse(formatSpec);
+            return {
+                valid: true,
+                formatType: "json-schema",
+                issues: [],
+                suggestions: [],
+                metadata: {
+                    structureType: "json"
+                }
+            };
+        }
+        catch (e) {
+            return {
+                valid: false,
+                formatType: "json-schema",
+                issues: [{
+                        type: "syntax-error",
+                        description: `Invalid JSON: ${e.message}`,
+                        severity: "error"
+                    }],
+                suggestions: ["Ensure the format specification is valid JSON."],
+                metadata: {
+                    structureType: "json"
+                }
+            };
+        }
+    }
+    // flex-md validation
+    const spec = parseOutputFormatSpec(formatSpec);
+    if (!formatSpec.toLowerCase().includes("output format")) {
+        issues.push({
+            type: "missing-heading",
+            description: "Missing '## Output format' heading.",
+            severity: "error",
+            suggestion: "Add '## Output format' to start the specification block."
+        });
+    }
+    if (!spec || spec.sections.length === 0) {
+        issues.push({
+            type: "missing-section",
+            description: "No sections detected in the specification.",
+            severity: "error",
+            suggestion: "Add at least one section using the '- Name — Kind' format."
+        });
+    }
+    const valid = !issues.some(i => i.severity === "error");
+    if (!valid) {
+        suggestions.push(...issues.map(i => i.suggestion).filter((s) => !!s));
+    }
+    return {
+        valid,
+        formatType: "flex-md",
+        issues,
+        suggestions,
+        metadata: {
+            sectionCount: spec?.sections.length ?? 0,
+            hasContainer: formatSpec.includes("```"),
+            structureType: "markdown"
+        }
+    };
+}
 export function parseOutputFormatSpec(md, opts = {}) {
     const headingRx = opts.headingRegex ?? /^##\s*Output format\b/i;
     const lines = md.split("\n");

package/dist/ofs/stringify.d.ts

@@ -1,5 +1,5 @@
 import type { OutputFormatSpec } from "../types.js";
 /**
- * Convert an OutputFormatSpec to canonical Markdown format.
+ * Convert an OutputFormatSpec to a formal "Instructions Output Format Block".
  */
 export declare function stringifyOutputFormatSpec(spec: OutputFormatSpec): string;

package/dist/ofs/stringify.js

@@ -1,5 +1,5 @@
 /**
- * Convert an OutputFormatSpec to canonical Markdown format.
+ * Convert an OutputFormatSpec to a formal "Instructions Output Format Block".
  */
 export function stringifyOutputFormatSpec(spec) {
     const lines = [];

package/dist/types.d.ts

@@ -177,3 +177,69 @@ export interface IssuesEnvelope {
         bullets: string[];
     }>;
 }
+export interface ComplianceIssue {
+    type: "missing-section" | "missing-container" | "invalid-format" | "missing-heading" | "other";
+    description: string;
+    severity: "error" | "warning";
+    location?: {
+        start: number;
+        end: number;
+        line?: number;
+        column?: number;
+    };
+    suggestion?: string;
+}
+export interface ComplianceCheckResult {
+    meetsCompliance: boolean;
+    complianceLevel: "L0" | "L1" | "L2" | "L3";
+    issues: ComplianceIssue[];
+    suggestions: string[];
+    metadata?: {
+        hasContainer?: boolean;
+        hasRequiredSections?: boolean;
+        sectionCount?: number;
+        containerType?: "fenced-block" | "none";
+    };
+}
+export interface EnhancementChange {
+    type: "added-section" | "added-container" | "modified-section" | "added-guidance" | "other";
+    description: string;
+    location: {
+        start: number;
+        end: number;
+    };
+    content?: string;
+}
+export interface EnhancementResult {
+    enriched: string;
+    changes: EnhancementChange[];
+    originalLength: number;
+    enhancedLength: number;
+    metadata?: {
+        sectionsAdded?: number;
+        containerAdded?: boolean;
+        guidanceAdded?: boolean;
+    };
+}
+export interface FormatValidationIssue {
+    type: "syntax-error" | "missing-section" | "invalid-structure" | "invalid-markdown" | "missing-heading" | "other";
+    description: string;
+    severity: "error" | "warning";
+    location?: {
+        start: number;
+        end: number;
+        line?: number;
+    };
+    suggestion?: string;
+}
+export interface FormatValidationResult {
+    valid: boolean;
+    formatType: "flex-md" | "json-schema" | "other" | "unknown";
+    issues: FormatValidationIssue[];
+    suggestions: string[];
+    metadata?: {
+        sectionCount?: number;
+        hasContainer?: boolean;
+        structureType?: string;
+    };
+}

package/dist/validate/compliance.d.ts

@@ -0,0 +1,11 @@
+import { ComplianceCheckResult } from "../types.js";
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * Returns detailed results including what's missing or wrong.
+ */
+export declare function checkCompliance(instructions: string, complianceLevel: "L0" | "L1" | "L2" | "L3"): Promise<ComplianceCheckResult>;
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * @deprecated Use checkCompliance for detailed results.
+ */
+export declare function hasFlexMdContract(instructions: string, complianceLevel: "L0" | "L1" | "L2" | "L3"): Promise<boolean>;

package/dist/validate/compliance.js

@@ -0,0 +1,91 @@
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * Returns detailed results including what's missing or wrong.
+ */
+export async function checkCompliance(instructions, complianceLevel) {
+    const issues = [];
+    const suggestions = [];
+    const lower = instructions.toLowerCase();
+    const hasMarkdownMention = lower.includes("markdown");
+    const hasSectionMention = lower.includes("section") || lower.includes("heading");
+    const hasContainerMention = (lower.includes("fenced block") || lower.includes("```")) && (lower.includes("inside") || lower.includes("wrapped"));
+    const hasNoneRule = lower.includes("none") && lower.includes("empty");
+    const hasListRules = lower.includes("list rules") || (lower.includes("ordered list") && lower.includes("unordered list"));
+    const hasTableRules = lower.includes("table") && lower.includes("pipe");
+    const levelNum = parseInt(complianceLevel.slice(1));
+    // L0 requirements
+    if (levelNum >= 0) {
+        if (!hasMarkdownMention) {
+            issues.push({
+                type: "other",
+                description: "Instructions do not mention 'Markdown'.",
+                severity: "error",
+                suggestion: "Add 'Reply in Markdown.' to your instructions."
+            });
+        }
+    }
+    // L1 requirements
+    if (levelNum >= 1) {
+        if (!hasSectionMention) {
+            issues.push({
+                type: "missing-section",
+                description: "Instructions do not specify required sections or headings.",
+                severity: "error",
+                suggestion: "Include a list of required section headings."
+            });
+        }
+    }
+    // L2 requirements
+    if (levelNum >= 2) {
+        if (!hasContainerMention) {
+            issues.push({
+                type: "missing-container",
+                description: "Instructions do not require a fenced container block (L2+ requirement).",
+                severity: "error",
+                suggestion: "Add 'Return your entire answer inside a single ```markdown fenced block and nothing else.' to your instructions."
+            });
+        }
+    }
+    // L3 requirements
+    if (levelNum >= 3) {
+        if (!hasNoneRule) {
+            issues.push({
+                type: "other",
+                description: "Instructions are missing the 'None' rule for empty sections (L3 requirement).",
+                severity: "warning",
+                suggestion: "Add 'If a section is empty, write `None`.' to your instructions."
+            });
+        }
+        if (!hasListRules) {
+            issues.push({
+                type: "invalid-format",
+                description: "Instructions are missing specific list formatting rules (L3 requirement).",
+                severity: "warning",
+                suggestion: "Add bullet and numbered list formatting instructions."
+            });
+        }
+    }
+    const meetsCompliance = !issues.some(i => i.severity === "error");
+    if (!meetsCompliance) {
+        suggestions.push(...issues.map(i => i.suggestion).filter((s) => !!s));
+    }
+    return {
+        meetsCompliance,
+        complianceLevel,
+        issues,
+        suggestions,
+        metadata: {
+            hasContainer: hasContainerMention,
+            hasRequiredSections: hasSectionMention,
+            containerType: hasContainerMention ? "fenced-block" : "none"
+        }
+    };
+}
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * @deprecated Use checkCompliance for detailed results.
+ */
+export async function hasFlexMdContract(instructions, complianceLevel) {
+    const result = await checkCompliance(instructions, complianceLevel);
+    return result.meetsCompliance;
+}

package/dist/validate/connection.d.ts

@@ -0,0 +1,12 @@
+export interface ConnectionResult {
+    connected: boolean;
+    key: string;
+    normalizedKey: string;
+    path?: string[];
+    alternativeMatches?: string[];
+    suggestion?: string;
+}
+/**
+ * Checks if a specific key (section) is "connected" in the given markdown.
+ */
+export declare function checkConnection(md: string, key: string): ConnectionResult;

package/dist/validate/connection.js

@@ -0,0 +1,44 @@
+import { buildOutline } from "../md/outline.js";
+import { normalizeName } from "../md/parse.js";
+/**
+ * Checks if a specific key (section) is "connected" in the given markdown.
+ */
+export function checkConnection(md, key) {
+    const outline = buildOutline(md);
+    const normKey = normalizeName(key);
+    const path = [];
+    // Breadth-first search for the key
+    const queue = outline.nodes.map(n => ({ node: n, currentPath: [n.title] }));
+    const alternatives = [];
+    while (queue.length > 0) {
+        const { node, currentPath } = queue.shift();
+        if (node.key === normKey) {
+            return {
+                connected: true,
+                key,
+                normalizedKey: normKey,
+                path: currentPath
+            };
+        }
+        // Collect alternatives (any heading that exists)
+        alternatives.push(node.title);
+        for (const child of node.children) {
+            queue.push({ node: child, currentPath: [...currentPath, child.title] });
+        }
+    }
+    // Not found, look for fuzzy matches or common issues
+    const suggestions = [];
+    if (alternatives.length === 0) {
+        suggestions.push("The document appears to have no headings.");
+    }
+    else {
+        suggestions.push(`Available sections: ${alternatives.join(", ")}`);
+    }
+    return {
+        connected: false,
+        key,
+        normalizedKey: normKey,
+        alternativeMatches: alternatives,
+        suggestion: suggestions.join(" ")
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "3.1.0",
+  "version": "3.5.0",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",
@@ -20,6 +20,9 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "flex-md": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,7 +42,8 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
+    "@types/node": "^25.0.3",
     "typescript": "^5.6.3",
     "vitest": "^4.0.16"
   }
-}
+}