flex-md 4.7.1 → 4.7.3

package/README.md

@@ -34,6 +34,11 @@ Flex-MD is a TypeScript library for building and enforcing **Markdown Output Con
 npm install flex-md
 ```
 
+## Runtime Compatibility
+
+- Node LTS baseline: `>=18` (see `engines` in `package.json`).
+- Dual-surface consumption guidance for library authors is documented in [docs/consumption.md](./docs/consumption.md).
+
 ## Quick Start
 
 ### 1. Define your Output Format Spec (OFS) with System Parts

package/athenices-ai-gateway.md

@@ -0,0 +1,25 @@
+# athenices ai-gateway coordination
+
+## Primary signal
+
+The primary consumer bug report in this ecosystem was observed through `@athenices/ai-gateway` in the `extractJsonFromFlexMd` path.
+
+## Coordination policy
+
+1. Prefer fixing the gateway loader behavior first.
+2. Keep `flex-md` package-level behavior documented and smoke-tested.
+3. Only change `flex-md` runtime format outputs (for example, introducing a true ESM build) if gateway-side fixes still leave reproducible runtime failures.
+
+## flex-md package notes
+
+- `flex-md` currently exposes `import` and `require` export conditions.
+- Both resolved runtime files are currently CommonJS output.
+- Package-level smoke coverage includes:
+  - direct `require` and `import` checks from local build artifacts,
+  - package-name resolution checks via tarball install in a temp consumer.
+
+## woroces ai-skills interaction
+
+`@woroces/ai-skills` uses dynamic `import("flex-md")` in `parseFlexMd` when the gateway does not provide parsed payloads.
+
+Improving gateway payload behavior reduces reliance on this fallback import path.

package/dist/__tests__/diagnostics.test.js

@@ -1,61 +1,59 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const vitest_1 = require("vitest");
-const index_js_1 = require("../index.js");
-(0, vitest_1.describe)("Diagnostics", () => {
-    (0, vitest_1.describe)("checkCompliance", () => {
-        (0, vitest_1.it)("should return meetsCompliance: true for L0 if Markdown is mentioned", async () => {
-            const res = await (0, index_js_1.checkCompliance)("Reply in Markdown.", "L0");
-            (0, vitest_1.expect)(res.meetsCompliance).toBe(true);
-            (0, vitest_1.expect)(res.issues).toHaveLength(0);
-        });
-        (0, vitest_1.it)("should return issues for L2 if container is missing", async () => {
-            const res = await (0, index_js_1.checkCompliance)("Reply in Markdown. Include headings.", "L2");
-            (0, vitest_1.expect)(res.meetsCompliance).toBe(false);
-            (0, vitest_1.expect)(res.issues.some(i => i.type === "missing-container")).toBe(true);
-        });
-        (0, vitest_1.it)("should return false for hasFlexMdContract if requirements not met", async () => {
-            const ok = await (0, index_js_1.hasFlexMdContract)("Hello", "L0");
-            (0, vitest_1.expect)(ok).toBe(false);
+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);
         });
     });
-    (0, vitest_1.describe)("enrichInstructionsWithFlexMd", () => {
-        (0, vitest_1.it)("should append guidance to existing instructions", async () => {
-            const res = await (0, index_js_1.enrichInstructionsWithFlexMd)("Do a good job.", "L0");
-            (0, vitest_1.expect)(res.enriched).toContain("Do a good job.");
-            (0, vitest_1.expect)(res.enriched).toContain("Reply in Markdown.");
-            (0, vitest_1.expect)(res.changes).toHaveLength(1);
-            (0, vitest_1.expect)(res.metadata?.guidanceAdded).toBe(true);
-        });
-        (0, vitest_1.it)("should track container addition for L2", async () => {
-            const res = await (0, index_js_1.enrichInstructionsWithFlexMd)("Do a good job.", "L2");
-            (0, vitest_1.expect)(res.changes.some(c => c.type === "added-container")).toBe(true);
-            (0, vitest_1.expect)(res.metadata?.containerAdded).toBe(true);
+    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);
         });
     });
-    (0, vitest_1.describe)("validateFormat", () => {
-        (0, vitest_1.it)("should validate a correct flex-md OFS", async () => {
+    describe("validateFormat", () => {
+        it("should validate a correct flex-md OFS", async () => {
             const ofs = `## Output format\n- Summary — prose\n- Actions — list`;
-            const res = await (0, index_js_1.validateFormat)(ofs);
-            (0, vitest_1.expect)(res.valid).toBe(true);
-            (0, vitest_1.expect)(res.metadata?.sectionCount).toBe(2);
+            const res = await validateFormat(ofs);
+            expect(res.valid).toBe(true);
+            expect(res.metadata?.sectionCount).toBe(2);
         });
-        (0, vitest_1.it)("should return errors for missing heading", async () => {
+        it("should return errors for missing heading", async () => {
             const ofs = `- Summary — prose`;
-            const res = await (0, index_js_1.validateFormat)(ofs);
-            (0, vitest_1.expect)(res.valid).toBe(false);
-            (0, vitest_1.expect)(res.issues.some(i => i.type === "missing-heading")).toBe(true);
+            const res = await validateFormat(ofs);
+            expect(res.valid).toBe(false);
+            expect(res.issues.some(i => i.type === "missing-heading")).toBe(true);
         });
-        (0, vitest_1.it)("should validate JSON schema", async () => {
+        it("should validate JSON schema", async () => {
             const schema = `{"type": "object"}`;
-            const res = await (0, index_js_1.validateFormat)(schema, "json-schema");
-            (0, vitest_1.expect)(res.valid).toBe(true);
+            const res = await validateFormat(schema, "json-schema");
+            expect(res.valid).toBe(true);
         });
-        (0, vitest_1.it)("should fail on invalid JSON schema", async () => {
+        it("should fail on invalid JSON schema", async () => {
             const schema = `{"type": "object"`;
-            const res = await (0, index_js_1.validateFormat)(schema, "json-schema");
-            (0, vitest_1.expect)(res.valid).toBe(false);
-            (0, vitest_1.expect)(res.issues[0].type).toBe("syntax-error");
+            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,9 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const vitest_1 = require("vitest");
-const stringify_js_1 = require("../ofs/stringify.js");
-const enricher_js_1 = require("../ofs/enricher.js");
-(0, vitest_1.describe)("Instructions Output Format Block Generation", () => {
+import { describe, it, expect } from "vitest";
+import { stringifyOutputFormatSpec } from "../ofs/stringify.js";
+import { buildMarkdownGuidance } from "../ofs/enricher.js";
+describe("Instructions Output Format Block Generation", () => {
     const spec = {
         description: "Standard report format for technical analysis.",
         sections: [
@@ -23,31 +21,31 @@ const enricher_js_1 = require("../ofs/enricher.js");
         ],
         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`.");
+    it("should stringify an OFS object correctly", () => {
+        const md = stringifyOutputFormatSpec(spec);
+        expect(md).toContain("## Output format (Markdown)");
+        expect(md).toContain("Standard report format for technical analysis.");
+        expect(md).toContain("- Summary — text (required)");
+        expect(md).toContain("Description: A brief summary of the topic.");
+        expect(md).toContain("Instruction: Keep it under 3 sentences.");
+        expect(md).toContain("- Key Points — list (optional)");
+        expect(md).toContain("Description: Important takeaways.");
+        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.");
+    it("should build markdown guidance (L1) correctly", () => {
+        const guidance = buildMarkdownGuidance(spec, { level: 1 });
+        expect(guidance).toContain("Include these section headings somewhere");
+        expect(guidance).toContain("- Summary");
+        expect(guidance).toContain("Description: A brief summary of the topic.");
+        expect(guidance).toContain("Instruction: Keep it under 3 sentences.");
+        expect(guidance).toContain("- Key Points");
+        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");
+    it("should build markdown guidance (L3) correctly", () => {
+        const guidance = buildMarkdownGuidance(spec, { level: 3 });
+        expect(guidance).toContain("Return your entire answer inside a single ```markdown fenced block");
+        expect(guidance).toContain("- Summary");
+        expect(guidance).toContain("- Key Points (list)");
+        expect(guidance).toContain("Do not return JSON");
     });
 });

package/dist/__tests__/structural.test.js

@@ -1,30 +1,28 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const vitest_1 = require("vitest");
-const index_js_1 = require("../index.js");
-(0, vitest_1.describe)("Structural Diagnostics", () => {
-    (0, vitest_1.describe)("===key support", () => {
-        (0, vitest_1.it)("should parse ===key as a top-level section", () => {
+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 = (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");
+            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");
         });
     });
-    (0, vitest_1.describe)("checkConnection", () => {
-        (0, vitest_1.it)("should find a section by name", () => {
+    describe("checkConnection", () => {
+        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");
+            const res = checkConnection(md, "skills");
+            expect(res.connected).toBe(true);
+            expect(res.path).toContain("skills");
         });
-        (0, vitest_1.it)("should fail gracefully for missing sections", () => {
+        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");
+            const res = checkConnection(md, "missing");
+            expect(res.connected).toBe(false);
+            expect(res.suggestion).toContain("Overview");
         });
     });
 });

package/dist/__tests__/validate.test.js

@@ -1,8 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const vitest_1 = require("vitest");
-const validate_js_1 = require("../validate/validate.js");
-const issuesEnvelope_js_1 = require("../ofs/issuesEnvelope.js");
+import { describe, it, expect } from "vitest";
+import { validateMarkdownAgainstOfs } from "../validate/validate.js";
+import { parseIssuesEnvelope } from "../ofs/issuesEnvelope.js";
 const SPEC = {
     emptySectionValue: "None",
     sections: [
@@ -32,8 +30,8 @@ function mdL1Good() {
         "- U",
     ].join("\n");
 }
-(0, vitest_1.describe)("parseIssuesEnvelope()", () => {
-    (0, vitest_1.it)("detects envelope and extracts bullets", () => {
+describe("parseIssuesEnvelope()", () => {
+    it("detects envelope and extracts bullets", () => {
         const env = [
             "## Status",
             "Non-compliant output (cannot be repaired to the required format).",
@@ -50,17 +48,17 @@ function mdL1Good() {
             "## 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");
+        const parsed = parseIssuesEnvelope(env);
+        expect(parsed.isIssuesEnvelope).toBe(true);
+        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);
+describe("validateMarkdownAgainstOfs()", () => {
+    it("L0 accepts anything", () => {
+        const r = validateMarkdownAgainstOfs("whatever", SPEC, 0);
+        expect(r.ok).toBe(true);
     });
-    (0, vitest_1.it)("L1 fails when required section missing", () => {
+    it("L1 fails when required section missing", () => {
         const md = [
             "## Short answer",
             "Yes.",
@@ -68,21 +66,21 @@ function mdL1Good() {
             "## 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);
+        const r = validateMarkdownAgainstOfs(md, SPEC, 1);
+        expect(r.ok).toBe(false);
+        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);
+    it("L2 requires a single fenced markdown block", () => {
+        const r = validateMarkdownAgainstOfs(mdL1Good(), SPEC, 2);
+        expect(r.ok).toBe(false);
+        expect(r.issues.some(i => i.code === "CONTAINER_MISSING")).toBe(true);
     });
-    (0, vitest_1.it)("L2 passes with one fence containing valid L1", () => {
+    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);
+        const r = validateMarkdownAgainstOfs(md, SPEC, 2);
+        expect(r.ok).toBe(true);
     });
-    (0, vitest_1.it)("L3 enforces section kinds (Reasoning must be ordered list)", () => {
+    it("L3 enforces section kinds (Reasoning must be ordered list)", () => {
         const bad = [
             "```markdown",
             [
@@ -103,8 +101,8 @@ function mdL1Good() {
             ].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);
+        const r = validateMarkdownAgainstOfs(bad, SPEC, 3);
+        expect(r.ok).toBe(false);
+        expect(r.issues.some(i => i.code === "WRONG_SECTION_KIND")).toBe(true);
     });
 });

package/dist/cli/index.js

@@ -1,9 +1,7 @@
 #!/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.js");
+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") {
@@ -57,8 +55,8 @@ async function handleCheck(args) {
     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);
+    const content = readFileSync(resolve(file), "utf-8");
+    const result = await checkCompliance(content, level);
     if (result.meetsCompliance) {
         console.log("✅ Content meets compliance.");
     }
@@ -74,10 +72,10 @@ async function handleDiagnose(args) {
     const key = args[1];
     if (!file || !key)
         throw new Error("Usage: flex-md diagnose <file> <key>");
-    if (!(0, fs_1.existsSync)(file))
+    if (!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);
+    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(" -> ")}`);
     }
@@ -91,9 +89,9 @@ async function handleCreate(args) {
     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 content = existsSync(file) ? readFileSync(file, "utf-8") : "";
     const newContent = content + `\n\n## ${key}\n\n[Content for ${key}]\n`;
-    (0, fs_1.writeFileSync)(file, newContent);
+    writeFileSync(file, newContent);
     console.log(`✅ Section "${key}" created in ${file}`);
 }
 async function handleSync(args) {
@@ -101,10 +99,10 @@ async function handleSync(args) {
     const target = args[1];
     if (!source || !target)
         throw new Error("Usage: flex-md sync <source> <target>");
-    if (!(0, fs_1.existsSync)(source))
+    if (!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);
+    const content = readFileSync(source, "utf-8");
+    writeFileSync(target, content);
     console.log(`✅ Content synced from ${source} to ${target}`);
 }
 main();

package/dist/detect/json/detectIntent.js

@@ -1,6 +1,3 @@
-"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,
@@ -28,7 +25,7 @@ const TOOLING_PATTERNS = [
     /\btool\s+call\b/i,
     /\barguments\b.*\bjson\b/i,
 ];
-function detectJsonIntent(text) {
+export function detectJsonIntent(text) {
     const signals = [];
     const add = (rx, strength, idx, len) => {
         signals.push({