flex-md 1.0.0

package/README.md

@@ -0,0 +1,36 @@
+# flex-md
+
+Parse and stringify **FlexMD Frames**: semi-structured Markdown that is easy for humans + deterministic for machines.
+
+## Install
+
+```bash
+npm i flex-md
+```
+
+## Usage
+
+```javascript
+import { parseFlexMd, stringifyFlexMd } from "flex-md";
+
+const md = `[[message role=user id=m1]]
+@tags: auth, login
+Hello
+
+@payload:name: input
+\`\`\`json
+{"a":1}
+\`\`\`
+`;
+
+const doc = parseFlexMd(md);
+console.log(doc.frames[0]?.type); // "message"
+
+const back = stringifyFlexMd(doc, { skipEmpty: true });
+console.log(back);
+```
+
+### Notes
+- Frames start with: `[[type key=value ...]]`
+- Metadata lines: `@key: value`
+- Payload binding: `@payload:name: X` then the next fenced block is payload X

package/dist/index.cjs

@@ -0,0 +1,3 @@
+// Auto-generated CJS bridge for flex-md
+const m = await import('./index.js');
+module.exports = m;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { parseFlexMd } from "./parser.js";
+export { stringifyFlexMd } from "./stringify.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { parseFlexMd } from "./parser.js";
+export { stringifyFlexMd } from "./stringify.js";

package/dist/parser.d.ts

@@ -0,0 +1,2 @@
+import type { FlexDocument, ParseOptions } from "./types.js";
+export declare function parseFlexMd(input: string, options?: ParseOptions): FlexDocument;

package/dist/parser.js

@@ -0,0 +1,151 @@
+import { splitTokensPreservingQuotes, unquote } from "./util.js";
+const HEADER_RE = /^\[\[(.+)\]\]\s*$/;
+const META_RE = /^@([^:]+):\s*(.*)$/;
+const PAYLOAD_DECL_RE = /^@payload:name:\s*(.+)\s*$/;
+function parseHeader(inner) {
+    // Supports:
+    // 1) [[message role=user id=m1 ts=...]]
+    // 2) shorthand: [[user m1]] => type=message role=user id=m1
+    const tokens = splitTokensPreservingQuotes(inner.trim()).map(unquote);
+    if (tokens.length === 0)
+        return { type: "message" };
+    // shorthand: [[user m1]] or [[assistant m2]]
+    if (tokens.length === 2 && !tokens[0].includes("=") && !tokens[1].includes("=")) {
+        return { type: "message", role: tokens[0], id: tokens[1] };
+    }
+    const type = tokens[0];
+    const out = { type };
+    for (const t of tokens.slice(1)) {
+        const idx = t.indexOf("=");
+        if (idx <= 0)
+            continue;
+        const key = t.slice(0, idx).trim();
+        const val = unquote(t.slice(idx + 1).trim());
+        out[key] = val;
+    }
+    return out;
+}
+function parseMetaValue(key, value, arrayKeys) {
+    const v = value.trim();
+    if (!arrayKeys.has(key))
+        return v;
+    // comma-separated
+    const parts = v
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    return parts;
+}
+function tryParsePayload(lang, raw) {
+    const l = (lang ?? "").toLowerCase();
+    if (l === "json") {
+        try {
+            const value = JSON.parse(raw);
+            return { lang, value, raw };
+        }
+        catch (e) {
+            return { lang, value: raw, raw, parseError: String(e?.message ?? e) };
+        }
+    }
+    return { lang, value: raw, raw };
+}
+export function parseFlexMd(input, options = {}) {
+    const arrayKeys = new Set((options.arrayMetaKeys ?? ["tags", "refs"]).map((s) => s.trim()));
+    const lines = input.split("\n");
+    const endsWithNewline = input.endsWith("\n");
+    const frames = [];
+    let cur = null;
+    // body accumulator for current frame (excluding meta and payload blocks)
+    let bodyLines = [];
+    // payload state: if declared, next code fence becomes its payload
+    let pendingPayloadName = null;
+    function flushCurrent() {
+        if (!cur)
+            return;
+        const body = bodyLines.join("\n");
+        // Preserve original trailing newline behavior inside body (best-effort):
+        cur.body_md = body.length ? body + "\n" : "";
+        // Trim to empty if it's only whitespace/newlines
+        if (cur.body_md.trim().length === 0)
+            delete cur.body_md;
+        frames.push(cur);
+        cur = null;
+        bodyLines = [];
+        pendingPayloadName = null;
+    }
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Frame header
+        const hm = line.match(HEADER_RE);
+        if (hm) {
+            flushCurrent();
+            cur = { ...parseHeader(hm[1]) };
+            i++;
+            continue;
+        }
+        // If we haven't seen a header yet, start an implicit frame.
+        cur ??= { type: "message" };
+        // Payload declaration
+        const pm = line.match(PAYLOAD_DECL_RE);
+        if (pm) {
+            pendingPayloadName = pm[1].trim();
+            i++;
+            continue;
+        }
+        // If a payload was declared, capture the next fenced code block
+        if (pendingPayloadName) {
+            const fenceStart = line.match(/^(```|~~~)\s*([A-Za-z0-9_-]+)?\s*$/);
+            if (fenceStart) {
+                const fence = fenceStart[1];
+                const lang = fenceStart[2]?.trim();
+                const rawLines = [];
+                i++;
+                while (i < lines.length && lines[i].trimEnd() !== fence) {
+                    rawLines.push(lines[i]);
+                    i++;
+                }
+                // consume closing fence if present
+                if (i < lines.length && lines[i].trimEnd() === fence)
+                    i++;
+                const raw = rawLines.join("\n");
+                cur.payloads ??= {};
+                cur.payloads[pendingPayloadName] = tryParsePayload(lang, raw);
+                pendingPayloadName = null;
+                continue;
+            }
+            else {
+                // payload declared but no fence; treat as body line
+                bodyLines.push(line);
+                pendingPayloadName = null;
+                i++;
+                continue;
+            }
+        }
+        // Metadata line
+        const mm = line.match(META_RE);
+        if (mm) {
+            const key = mm[1].trim();
+            const value = mm[2] ?? "";
+            cur.meta ??= {};
+            cur.meta[key] = parseMetaValue(key, value, arrayKeys);
+            i++;
+            continue;
+        }
+        // Default: part of body
+        bodyLines.push(line);
+        i++;
+    }
+    flushCurrent();
+    // Preserve overall trailing newline more closely: if input had no final newline,
+    // avoid forcing one by trimming last frame body newline.
+    if (!endsWithNewline && frames.length > 0) {
+        const last = frames[frames.length - 1];
+        if (typeof last.body_md === "string" && last.body_md.endsWith("\n")) {
+            last.body_md = last.body_md.slice(0, -1);
+            if (last.body_md.trim().length === 0)
+                delete last.body_md;
+        }
+    }
+    return { frames };
+}

package/dist/stringify.d.ts

@@ -0,0 +1,2 @@
+import type { FlexDocument, StringifyOptions } from "./types.js";
+export declare function stringifyFlexMd(doc: FlexDocument, options?: StringifyOptions): string;

package/dist/stringify.js

@@ -0,0 +1,110 @@
+import { isBlank, isEmptyObject, quoteIfNeeded } from "./util.js";
+function metaValueToString(key, v, arrayKeys) {
+    if (v === null)
+        return null;
+    if (Array.isArray(v)) {
+        if (v.length === 0)
+            return null;
+        // Render arrays as comma-separated by default for known keys, otherwise JSON
+        if (arrayKeys.has(key))
+            return v.join(", ");
+        return JSON.stringify(v);
+    }
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    // Fallback
+    return String(v);
+}
+function shouldSkipMetaValue(v) {
+    if (v === null || v === undefined)
+        return true;
+    if (typeof v === "string" && v.trim() === "")
+        return true;
+    if (Array.isArray(v) && v.length === 0)
+        return true;
+    return false;
+}
+function buildHeader(frame) {
+    // [[type key=value ...]]
+    const parts = [`[[${frame.type}`];
+    // include common attrs if present (role/id/ts) and any other top-level string attrs
+    const knownOrder = ["role", "id", "ts"];
+    for (const k of knownOrder) {
+        const val = frame[k];
+        if (typeof val === "string" && val.trim().length) {
+            parts.push(`${String(k)}=${quoteIfNeeded(val)}`);
+        }
+    }
+    // If the user adds extra header-like attributes, you can support them by convention:
+    // we intentionally do NOT auto-include unknown keys to keep JSON schema clean.
+    return parts.join(" ") + "]]";
+}
+export function stringifyFlexMd(doc, options = {}) {
+    const skipEmpty = options.skipEmpty ?? true;
+    const fence = options.fence ?? "```";
+    const arrayKeys = new Set((options.arrayMetaKeys ?? ["tags", "refs"]).map((s) => s.trim()));
+    const out = [];
+    for (let idx = 0; idx < doc.frames.length; idx++) {
+        const frame = doc.frames[idx];
+        out.push(buildHeader(frame));
+        // META
+        if (!isEmptyObject(frame.meta)) {
+            const keys = Object.keys(frame.meta ?? {});
+            for (const k of keys) {
+                const v = frame.meta[k];
+                if (skipEmpty && shouldSkipMetaValue(v))
+                    continue;
+                const rendered = metaValueToString(k, v, arrayKeys);
+                if (skipEmpty && (rendered === null || rendered.trim() === ""))
+                    continue;
+                out.push(`@${k}: ${rendered ?? ""}`.trimEnd());
+            }
+        }
+        // BODY
+        if (typeof frame.body_md === "string") {
+            const body = frame.body_md;
+            if (!(skipEmpty && isBlank(body))) {
+                // Keep body verbatim, but avoid double-blanking: ensure we don't accidentally
+                // merge with next header by always preserving its internal newlines.
+                const normalized = body.endsWith("\n") ? body.slice(0, -1) : body;
+                if (normalized.length > 0)
+                    out.push(normalized);
+            }
+        }
+        // PAYLOADS
+        const payloads = frame.payloads ?? {};
+        const payloadNames = Object.keys(payloads);
+        if (!(skipEmpty && payloadNames.length === 0)) {
+            for (const name of payloadNames) {
+                const p = payloads[name];
+                // Skip empty payload if requested
+                if (skipEmpty &&
+                    (p == null ||
+                        (typeof p.raw === "string" && p.raw.trim() === "") ||
+                        (p.value == null && (p.raw ?? "").trim() === ""))) {
+                    continue;
+                }
+                out.push(`@payload:name: ${name}`);
+                const lang = (p.lang ?? "").trim();
+                const header = lang ? `${fence}${lang}` : fence;
+                out.push(header);
+                // Prefer raw if present; if missing raw but value exists, serialize value
+                const raw = typeof p.raw === "string" && p.raw.length > 0
+                    ? p.raw
+                    : p.value !== undefined
+                        ? typeof p.value === "string"
+                            ? p.value
+                            : JSON.stringify(p.value, null, 2)
+                        : "";
+                out.push(raw);
+                out.push(fence);
+            }
+        }
+        // Frame separator: blank line between frames (readable) unless last
+        if (idx !== doc.frames.length - 1)
+            out.push("");
+    }
+    return out.join("\n") + "\n";
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export type FlexMetaValue = string | string[] | number | boolean | null;
+export interface FlexPayload {
+    /** Language from the fenced block, e.g. "json", "yaml", "text" */
+    lang?: string;
+    /** Parsed value for json fences; otherwise a string raw value */
+    value: unknown;
+    /** Raw text inside the fence (no surrounding ``` lines) */
+    raw: string;
+    /** If lang=json but parsing failed */
+    parseError?: string;
+}
+export interface FlexFrame {
+    type: string;
+    role?: string;
+    id?: string;
+    ts?: string;
+    /** Metadata from @key: lines */
+    meta?: Record<string, FlexMetaValue>;
+    /** Body markdown between header/meta and next frame header */
+    body_md?: string;
+    /** Payloads keyed by @payload:name: X */
+    payloads?: Record<string, FlexPayload>;
+}
+export interface FlexDocument {
+    frames: FlexFrame[];
+}
+export interface ParseOptions {
+    /**
+     * Which metadata keys should be split by commas into string[]
+     * Default: ["tags", "refs"]
+     */
+    arrayMetaKeys?: string[];
+}
+export interface StringifyOptions {
+    /**
+     * If true, omit empty sections when converting JSON -> FlexMD.
+     * Default: true
+     */
+    skipEmpty?: boolean;
+    /**
+     * Which meta keys should be rendered as comma-separated lists if arrays.
+     * Default: ["tags", "refs"]
+     */
+    arrayMetaKeys?: string[];
+    /**
+     * Preferred fence marker. Default: "```"
+     */
+    fence?: "```" | "~~~";
+}

package/dist/types.js

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

package/dist/util.d.ts

@@ -0,0 +1,5 @@
+export declare function isBlank(s: unknown): boolean;
+export declare function isEmptyObject(o: unknown): boolean;
+export declare function splitTokensPreservingQuotes(input: string): string[];
+export declare function unquote(s: string): string;
+export declare function quoteIfNeeded(value: string): string;

package/dist/util.js

@@ -0,0 +1,64 @@
+export function isBlank(s) {
+    return typeof s !== "string" || s.trim().length === 0;
+}
+export function isEmptyObject(o) {
+    if (!o || typeof o !== "object")
+        return true;
+    return Object.keys(o).length === 0;
+}
+export function splitTokensPreservingQuotes(input) {
+    // Splits by whitespace, but keeps "quoted strings" and 'quoted strings'
+    // Example: key="hello world" -> single token
+    const tokens = [];
+    let i = 0;
+    while (i < input.length) {
+        while (i < input.length && /\s/.test(input[i]))
+            i++;
+        if (i >= input.length)
+            break;
+        const ch = input[i];
+        if (ch === '"' || ch === "'") {
+            const quote = ch;
+            i++;
+            let buf = "";
+            while (i < input.length) {
+                const c = input[i];
+                if (c === "\\" && i + 1 < input.length) {
+                    // minimal escape support
+                    buf += input[i + 1];
+                    i += 2;
+                    continue;
+                }
+                if (c === quote) {
+                    i++;
+                    break;
+                }
+                buf += c;
+                i++;
+            }
+            tokens.push(quote + buf + quote);
+            continue;
+        }
+        // unquoted token
+        let start = i;
+        while (i < input.length && !/\s/.test(input[i]))
+            i++;
+        tokens.push(input.slice(start, i));
+    }
+    return tokens;
+}
+export function unquote(s) {
+    const t = s.trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+export function quoteIfNeeded(value) {
+    // Only quote if whitespace or special chars likely to break header tokenization
+    if (/[\s\]]/.test(value) || value.includes('"') || value.includes("'")) {
+        // Use JSON-style quoting for safety
+        return JSON.stringify(value);
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "flex-md",
+  "version": "1.0.0",
+  "description": "Parse and stringify FlexMD Frames (semi-structured Markdown) to/from JSON.",
+  "license": "MIT",
+  "author": "",
+  "keywords": ["markdown", "parser", "serialization", "llm", "prompting", "semi-structured"],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc && node ./scripts/cjs-bridge.mjs",
+    "test": "node ./dist/index.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}