mdeval 1.0.0 → 1.2.0

package/README.md

@@ -26,7 +26,7 @@ const pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));
 -->
 ```
 
-Full Node.js, ESM imports, and top-level `await` are supported.
+Full Node.js, ESM imports, top-level `await`, and shell commands via [`$`](https://google.github.io/zx/) are supported.
 
 A **value marker** is where the result appears. It starts with `<!--mdeval ` (with a space) followed by a JavaScript expression:
 
@@ -40,7 +40,9 @@ The `1.0.0` between `-->` and `<!--/mdeval-->` is the current value — it gets
 mdeval README.md
 ```
 
-The file is updated in-place. You can pass multiple files at once: `mdeval README.md docs/*.md`
+The file is updated in-place. You can pass multiple files or glob patterns: `mdeval README.md "docs/**/*.md"`.
+
+`node_modules` and hidden directories are automatically excluded from glob expansion.
 
 ## Notes
 
@@ -54,6 +56,14 @@ The file is updated in-place. You can pass multiple files at once: `mdeval READM
 
   In large documents, this IIFE pattern lets you keep logic next to the marker it serves instead of in a distant script block.
 
+- Marker expressions are **auto-awaited** — promises resolve automatically, so you can use `fetch()` or any async API directly in a marker without wrapping it in a script block.
+
+- **`$`** from [zx](https://google.github.io/zx/) is available as a global — run shell commands directly in markers:
+
+  ```markdown
+  <!--mdeval $`git branch --show-current`-->main<!--/mdeval-->
+  ```
+
 - If your value starts with a heading, list, or other block element, wrap it with **`block()`** so it renders on its own line. `block()` is a global helper that adds newlines before and after the value.
 
 - You can **import from other `.md` files**. Only the script blocks are executed — no markers are processed:
@@ -81,9 +91,13 @@ The file is updated in-place. You can pass multiple files at once: `mdeval READM
 ```markdown
 <!--mdeval
 import { table, bold, link } from 'md-pen';
-const deps = [['cleye', '^2.3.0'], ['md-pen', '^0.0.2']];
-const depsTable = table(deps.map(([name, v]) => [
-  link(`https://npm.im/${name}`, bold(name)), v
+const deps = [
+  ['cleye', '^2.3.0'],
+  ['md-pen', '^0.0.2'],
+];
+const depsTable = table(deps.map(([name, version]) => [
+  link(`https://npm.im/${name}`, bold(name)),
+  version,
 ]));
 -->
 
@@ -98,3 +112,7 @@ const depsTable = table(deps.map(([name, v]) => [
 ## Agent Skills
 
 This package ships with a built-in [agent skill](./skills/mdeval/SKILL.md) for AI coding assistants. Set up [`skills-npm`](https://github.com/antfu/skills-npm) to automatically discover it.
+
+## Related
+
+- [comment-mark](https://github.com/privatenumber/comment-mark) — Same idea of using HTML comment placeholders, but you write the script externally and pass values in via a JavaScript API. Useful when you want to keep the logic separate from the Markdown.

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-var h=Object.defineProperty;var a=(r,o)=>h(r,"name",{value:o,configurable:!0});import{register as g}from"node:module";import u from"node:fs/promises";import w from"node:path";import{cli as E}from"cleye";import{pathToFileURL as y}from"node:url";import{p as M,b as $,E as R,M as b,C,a as S}from"./parse-markdown-ChGEvmW3.mjs";import"md4x";const k=a(r=>{if(r==null)throw new Error(`Cannot interpolate ${r} \u2014 this is likely a bug in your script`);return typeof r=="string"?r:typeof r=="object"?JSON.stringify(r):String(r)},"coerceValue"),v=a(async(r,o)=>{const{markers:e}=M(r);if(e.length===0)return r;const n=await import(y(o).href),f=$(e),m=new Map,d=a((t,l)=>{const i=m.get(t);if(i!==void 0)return i;const s=k(n[`${R}${t}`]);if(s.includes(b)||s.includes(`${C}
-`)||s.includes(S))throw new Error(`Expression "${l}" produced a value containing mdeval comment syntax, which would corrupt the document on re-parse`);return m.set(t,s),s},"resolveValue"),c=[];let p=0;for(const t of e){const l=f.get(t.expression),i=d(l,t.expression);c.push(r.slice(p,t.contentStart),i),p=t.contentEnd}return c.push(r.slice(p)),c.join("")},"processSource");g("#md-loader",import.meta.url),globalThis.block=r=>`
+var g=Object.defineProperty;var l=(r,o)=>g(r,"name",{value:o,configurable:!0});import m from"node:fs/promises";import h from"node:path";import{cli as w}from"cleye";import{glob as E}from"tinyglobby";import{$ as y}from"zx";import{register as $}from"node:module";import{pathToFileURL as b}from"node:url";import{p as x,b as M,E as S,M as P,C as R,a as _}from"./parse-markdown-ChGEvmW3.mjs";import"md4x";const T=l(r=>{if(r==null)throw new Error(`Cannot interpolate ${r} \u2014 this is likely a bug in your script`);return typeof r=="string"?r:typeof r=="object"?Symbol.toPrimitive in r?String(r):JSON.stringify(r):String(r)},"coerceValue");$("#md-loader",import.meta.url);const k=l(async(r,o)=>{const{markers:t}=x(r);if(t.length===0)return r;const s=await import(b(o).href),p=M(t),u=await Promise.all(Array.from(p).map(async([e,c])=>{const n=T(await s[`${S}${c}`]);if(n.includes(P)||n.includes(`${R}
+`)||n.includes(_))throw new Error(`Expression "${e}" produced a value containing mdeval comment syntax, which would corrupt the document on re-parse`);return n})),i=[];let a=0;for(const e of t){const c=p.get(e.expression);i.push(r.slice(a,e.contentStart),u[c]),a=e.contentEnd}return i.push(r.slice(a)),i.join("")},"processSource");globalThis.block=r=>`
 ${String(r)}
-`;const x=E({name:"mdeval",parameters:["<files...>"]});await Promise.all(x._.files.map(async r=>{try{const o=w.resolve(r),e=await u.readFile(o,"utf8"),n=await v(e,o);n!==e&&(await u.writeFile(o,n,"utf8"),console.log(`Updated: ${r}`))}catch(o){console.error(`Error processing ${r}:`,o instanceof Error?o.message:o),process.exitCode=1}}));
+`,globalThis.$=y;const C=w({name:"mdeval",parameters:["<files...>"]}),d=C._.files,N=d.some(r=>r.includes("node_modules")),f=await E(d,{ignore:N?[]:["**/node_modules/**"]});f.length===0&&(console.error("No files matched the given patterns"),process.exit(1)),await Promise.all(f.map(async r=>{try{const o=h.resolve(r),t=await m.readFile(o,"utf8"),s=await k(t,o);s!==t&&(await m.writeFile(o,s,"utf8"),console.log(`Updated: ${r}`))}catch(o){console.error(`Error processing ${r}:`,o instanceof Error?o.message:o),process.exitCode=1}}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeval",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Evaluate JavaScript in markdown HTML comments and interpolate results in-place",
   "keywords": [
     "markdown",
@@ -29,6 +29,8 @@
   },
   "dependencies": {
     "cleye": "^2.3.0",
-    "md4x": "^0.0.25"
+    "md4x": "^0.0.25",
+    "tinyglobby": "^0.2.15",
+    "zx": "8.8.5-lite"
   }
 }

package/skills/mdeval/SKILL.md

@@ -14,7 +14,7 @@ Two types of HTML comments — invisible when rendered:
 | Script block | `<!--mdeval\n...\n-->` | Define variables, imports, logic. Starts with `<!--mdeval` + newline |
 | Value marker | `<!--mdeval EXPR-->value<!--/mdeval-->` | Interpolate expression result. Starts with `<!--mdeval ` + space |
 
-Script blocks run as ESM with full Node.js access and top-level `await`. All blocks in a file merge into one module — imports and variables are shared across blocks and markers. `import.meta` points to the markdown file.
+Script blocks run as ESM with full Node.js access and top-level `await`. All blocks in a file merge into one module — imports and variables are shared across blocks and markers. `import.meta` points to the markdown file. Marker expressions are auto-awaited, so promises resolve automatically.
 
 ## Marker Expressions
 
@@ -36,10 +36,38 @@ Duplicate expressions across markers are evaluated once and reused.
 | `string` | As-is |
 | `number`, `boolean`, `bigint` | `String(value)` |
 | `object`, `array` | `JSON.stringify(value)` |
+| object with `Symbol.toPrimitive` | `String(value)` (e.g. zx `ProcessOutput`) |
+| `Promise` | Auto-awaited, then coerced |
 | `undefined`, `null` | Error |
 
+## Globals
+
+| Global | Description |
+|--------|-------------|
+| `block(value)` | Wraps value with newlines for block-level rendering |
+| `$` | [zx](https://google.github.io/zx/) shell — run commands via tagged templates: `` $`git branch` `` |
+
+## CLI
+
+```bash
+mdeval README.md                    # single file
+mdeval README.md docs/guide.md      # multiple files
+mdeval "docs/**/*.md"               # glob pattern
+mdeval "**/*.md"                    # recursive — node_modules and dotdirs auto-excluded
+```
+
+Supports full glob syntax including `**` recursive, `{a,b}` brace expansion, and `!` negation.
+
+`node_modules` and hidden directories (`.git`, `.next`, etc.) are automatically excluded from glob expansion. No need to manually negate them. To explicitly include `node_modules`, reference it in the pattern: `mdeval "node_modules/pkg/*.md"`.
+
 ## Patterns
 
+### Shell commands
+
+````markdown
+<!--mdeval $`git branch --show-current`-->main<!--/mdeval-->
+````
+
 ### Read package.json
 
 ````markdown
@@ -116,3 +144,5 @@ const x = String.fromCharCode(45, 45, 62);
 **Use IIFEs to co-locate logic.** In large docs, keep marker-specific computation inline instead of in a distant script block: `<!--mdeval (() => { ... })()-->`.
 
 **Markers in code blocks are safe.** Fenced, indented, and inline code won't be touched — safe to document mdeval syntax in your own README.
+
+**Never create a .md file with only a script block and no real content.** Markdown files must contain actual prose/documentation. For shared logic or utilities, create a `.js` or `.ts` file and import it from your markdown instead.