flex-md 4.7.1 → 4.7.2

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 <22` (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/docs/consumption.md

@@ -0,0 +1,45 @@
+# flex-md consumption (library authors)
+
+This document is for library/tool authors (gateways, SDK adapters, orchestrators), not end-user apps.
+
+## Node support baseline
+
+- `flex-md` supports Node LTS in the range `>=18 <22`.
+- Release validation should run `npm run build` then `npm run test:smoke`.
+
+## Export map behavior
+
+`flex-md` publishes conditional exports:
+
+- `import` -> `./dist/index.js`
+- `require` -> `./dist/index.cjs`
+- `types` -> `./dist/index.d.ts`
+
+Today, both runtime entries are CommonJS output. The `import` condition gives Node and bundlers a resolver path, but does not currently mean ESM syntax output.
+
+## CJS bridge during publish
+
+Build flow:
+
+1. `tsc` emits CommonJS files into `dist/`
+2. `tsc -p tsconfig.cjs.json` emits CommonJS files into `dist-cjs/`
+3. `scripts/cjs-bridge.mjs` copies `dist-cjs/index.js` to `dist/index.cjs`
+
+This keeps a stable `require` entry while preserving the package export conditions expected by consumers.
+
+## Supported consumption patterns
+
+- CommonJS: `const flex = require("flex-md")`
+- ESM runtime: `import * as flex from "flex-md"`
+- Dynamic fallback import: `const flex = await import("flex-md")`
+
+For runtime confidence, use package-based smoke tests (install from tarball and load by package name) instead of importing local `dist/` paths only.
+
+## Bundler caveats
+
+Some bundlers treat the `import` condition as if it must point to ESM syntax. In those environments:
+
+- prefer default package resolution first,
+- then apply bundler-specific externalization/transpile settings if needed.
+
+If a bug reproduces only under one bundler graph, treat that as a consumer integration issue and document the supported loader pattern for that environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "4.7.1",
+  "version": "4.7.2",
   "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 @@
     "esm": true
   },
   "type": "commonjs",
+  "engines": {
+    "node": ">=18 <22"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -36,6 +39,7 @@
   "files": [
     "dist",
     "docs",
+    "athenices-ai-gateway.md",
     "README.md",
     "SPEC.md"
   ],
@@ -43,18 +47,12 @@
     "build": "tsc && tsc -p tsconfig.cjs.json && node ./scripts/cjs-bridge.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:smoke": "node test/smoke-require.cjs && node test/smoke-import.mjs",
+    "test:smoke": "node test/smoke-require.cjs && node test/smoke-import.mjs && node test/smoke-package-resolution.cjs",
     "deps:latest": "npx npm-check-updates -u && npm install"
   },
-  "devDependencies": {
-    "@types/node": "^25.0.3",
-    "tsx": "^4.21.0",
-    "typescript": "^5.6.3",
-    "vitest": "^4.0.16"
-  },
+  "devDependencies": {},
   "dependencies": {
     "micro-logs": "^1.0.0",
-    "nd": "^1.2.0",
     "nx-helpers": "^1.5.0",
     "nx-json-parser": "^1.3.0",
     "nx-md-parser": "^2.2.1"