@jasonbelmonti/markdown-engine 2.0.0 → 3.1.0

package/fixtures/declarative-validation/examples/okf-v0.1/fail/invalid-log-date/log.md

@@ -0,0 +1,5 @@
+# Directory Update Log
+
+## 2026-02-30
+
+* **Update**: This date heading is intentionally invalid.

package/fixtures/declarative-validation/examples/okf-v0.1/fail/missing-concept-type/concepts/customer-metric.md

@@ -0,0 +1,8 @@
+---
+title: Customer Metric
+description: A concept fixture that omits the required type field.
+---
+
+# Definition
+
+This fixture is intentionally missing `type` frontmatter for OKF concept validation.

package/fixtures/declarative-validation/examples/okf-v0.1/fail/non-root-index-frontmatter/datasets/index.md

@@ -0,0 +1,7 @@
+---
+title: Datasets
+---
+
+# Datasets
+
+* [Customer metric](customer-metric.md) - This non-root index intentionally has frontmatter.

package/fixtures/declarative-validation/examples/okf-v0.1/pass/datasets/index.md

@@ -0,0 +1,3 @@
+# Datasets
+
+* [Sales dataset](sales.md) - Sales knowledge assets.

package/fixtures/declarative-validation/examples/okf-v0.1/pass/datasets/sales.md

@@ -0,0 +1,16 @@
+---
+type: BigQuery Dataset
+title: Sales Dataset
+description: Sales reporting assets for the example bundle.
+resource: https://example.com/bigquery/datasets/sales
+tags: [sales, reporting]
+timestamp: 2026-06-15T00:00:00Z
+---
+
+# Schema
+
+The sales dataset contains curated order and customer reporting tables.
+
+# Citations
+
+[1] [Internal sales catalog](https://example.com/catalog/sales)

package/fixtures/declarative-validation/examples/okf-v0.1/pass/index.md

@@ -0,0 +1,8 @@
+---
+okf_version: "0.1"
+---
+
+# Knowledge Bundle
+
+* [Datasets](datasets/) - Curated data assets and related concepts.
+* [Incident response](playbooks/incident-response.md) - Operational playbook concept.

package/fixtures/declarative-validation/examples/okf-v0.1/pass/log.md

@@ -0,0 +1,9 @@
+# Directory Update Log
+
+## 2026-06-15
+
+* **Creation**: Added the initial OKF v0.1 example bundle.
+
+## 2026-06-01
+
+* **Initialization**: Established the example knowledge bundle structure.

package/fixtures/declarative-validation/examples/okf-v0.1/pass/playbooks/incident-response.md

@@ -0,0 +1,17 @@
+---
+type: Playbook
+title: Incident Response
+description: Triage steps for a data freshness incident.
+tags: [oncall, freshness]
+timestamp: 2026-06-15T00:00:00Z
+---
+
+# Trigger
+
+A freshness alert fires when an expected dataset update is delayed.
+
+# Steps
+
+1. Check the ingestion dashboard.
+2. Notify the on-call owner.
+3. Record the incident in the bundle log.

package/fixtures/declarative-validation/examples/okf-v0.1/profiles/concept.yaml

@@ -0,0 +1,14 @@
+syntaxVersion: markdown-engine.validation@v2
+documentVersion: 1.0.0
+rules:
+  - id: okf.concept.frontmatter
+    select:
+      target: document
+    assert:
+      frontmatterShape:
+        presence: required
+        fields:
+          - field: type
+            required: true
+            valueType: string
+            nonEmpty: true

package/fixtures/declarative-validation/examples/okf-v0.1/profiles/log.yaml

@@ -0,0 +1,10 @@
+syntaxVersion: markdown-engine.validation@v2
+documentVersion: 1.0.0
+rules:
+  - id: okf.log.date-heading
+    select:
+      target: heading
+      depth: 2
+    assert:
+      textFormat:
+        format: isoDate

package/fixtures/declarative-validation/examples/okf-v0.1/profiles/non-root-index.yaml

@@ -0,0 +1,9 @@
+syntaxVersion: markdown-engine.validation@v2
+documentVersion: 1.0.0
+rules:
+  - id: okf.non-root-index.no-frontmatter
+    select:
+      target: document
+    assert:
+      frontmatterShape:
+        presence: forbidden

package/fixtures/declarative-validation/examples/okf-v0.1/profiles/root-index.yaml

@@ -0,0 +1,12 @@
+syntaxVersion: markdown-engine.validation@v2
+documentVersion: 1.0.0
+rules:
+  - id: okf.root-index.version-frontmatter
+    select:
+      target: document
+    assert:
+      frontmatterShape:
+        fields:
+          - field: okf_version
+            valueType: string
+            nonEmpty: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonbelmonti/markdown-engine",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "description": "Deterministic Markdown parsing and validation engine package.",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,9 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "dist-bundled",
+    "scripts/install-markdown-engine-cli.sh",
+    "skills",
     "docs/contracts",
     "fixtures/declarative-validation/examples",
     "CHANGELOG.md",
@@ -42,9 +45,11 @@
   "scripts": {
     "clean": "node scripts/clean-dist.mjs",
     "build": "npm run clean && tsc -p tsconfig.json",
+    "build:cli:bundled": "node scripts/build-bundled-cli.mjs",
+    "build:cli-bundle": "node scripts/build-cli-bundle.mjs",
     "prepack": "npm run release:verify",
     "prepublishOnly": "npm run release:verify",
-    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run docs:rich-ir-contract && npm run docs:declarative-validation-contract && npm run audit:declarative-validation-boundary && npm run build && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
+    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run docs:rich-ir-contract && npm run docs:declarative-validation-contract && npm run audit:declarative-validation-boundary && npm run build && npm run build:cli:bundled && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
     "release:check-clean": "git diff --check HEAD -- && git diff --exit-code HEAD --",
     "snapshots:update:parser": "npm run build && vitest run tests/parser-fixtures.test.ts -u \"--exclude=.worktrees/**\"",
     "snapshots:update:rules": "npm run build && vitest run tests/rules.test.ts -u \"--exclude=.worktrees/**\"",
@@ -65,7 +70,7 @@
     "test:validation:profile": "npm run build && vitest run tests/declarative-validation-profile.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:compiler": "npm run build && vitest run tests/declarative-validation-compiler.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:selectors": "npm run build && vitest run tests/declarative-validation-selectors.test.ts \"--exclude=.worktrees/**\"",
-    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts tests/declarative-validation-frontmatter-shape-assertions.test.ts tests/declarative-validation-table-column-coverage-fixtures.test.ts tests/declarative-validation-grouped-rules-fixtures.test.ts tests/declarative-validation-when-skipped-rules-fixtures.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:diagnostics": "npm run build && vitest run tests/declarative-validation-diagnostics.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:cli": "npm run build && vitest run tests/declarative-validation-cli.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:examples": "npm run build && vitest run tests/declarative-validation-examples.test.ts \"--exclude=.worktrees/**\"",
@@ -83,6 +88,7 @@
   "devDependencies": {
     "@types/node": "^22.19.17",
     "cmark-gfm": "^0.9.0",
+    "esbuild": "^0.27.7",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
   },

package/scripts/install-markdown-engine-cli.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env sh
+set -eu
+
+VERSION="3.0.0"
+PACKAGE="@jasonbelmonti/markdown-engine"
+EXPECTED_SHA256="f61ab59e28eb92cccf4fd8073c090102e67a9397a7f0d208661ded14b879053d"
+DEFAULT_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
+MARKDOWN_ENGINE_HOME="${MARKDOWN_ENGINE_HOME:-$DEFAULT_DATA_HOME/markdown-engine}"
+MARKDOWN_ENGINE_BIN_DIR="${MARKDOWN_ENGINE_BIN_DIR:-$HOME/.local/bin}"
+INSTALL_DIR="$MARKDOWN_ENGINE_HOME/tools/markdown-engine/$VERSION"
+INSTALL_CLI="$INSTALL_DIR/markdown-engine-cli.mjs"
+BIN_DIR="$MARKDOWN_ENGINE_BIN_DIR"
+BIN_PATH="$BIN_DIR/markdown-engine"
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+REPO_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
+LOCAL_CLI="$REPO_ROOT/dist-bundled/markdown-engine-cli.mjs"
+PACKED_CLI_ENTRY="package/dist-bundled/markdown-engine-cli.mjs"
+TMP_DIR=""
+SOURCE_CLI=""
+
+cleanup() {
+  if [ -n "$TMP_DIR" ] && [ -d "$TMP_DIR" ]; then
+    rm -rf "$TMP_DIR"
+  fi
+}
+trap cleanup EXIT HUP INT TERM
+
+fail() {
+  printf 'install-markdown-engine-cli: %s\n' "$1" >&2
+  exit 1
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
+}
+
+sha256_of() {
+  shasum -a 256 "$1" | awk '{print $1}'
+}
+
+shell_quote() {
+  printf "'"
+  printf '%s' "$1" | sed "s/'/'\\\\''/g"
+  printf "'"
+}
+
+has_expected_sha() {
+  candidate_sha=$(sha256_of "$1")
+
+  if [ "$candidate_sha" = "$EXPECTED_SHA256" ]; then
+    return 0
+  fi
+
+  printf 'install-markdown-engine-cli: ignoring local CLI with unexpected SHA-256 for %s: %s\n' "$1" "$candidate_sha" >&2
+  return 1
+}
+
+resolve_source_cli() {
+  if [ -f "$LOCAL_CLI" ]; then
+    if has_expected_sha "$LOCAL_CLI"; then
+      SOURCE_CLI="$LOCAL_CLI"
+      return 0
+    fi
+  fi
+
+  require_command npm
+  require_command tar
+
+  TMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/markdown-engine-cli.XXXXXX")
+  pack_file=$(npm pack "$PACKAGE@$VERSION" --ignore-scripts --pack-destination "$TMP_DIR" --silent)
+
+  [ -n "$pack_file" ] || fail "npm pack did not return a tarball name"
+  [ -f "$TMP_DIR/$pack_file" ] || fail "npm pack tarball not found: $TMP_DIR/$pack_file"
+
+  tar -xzf "$TMP_DIR/$pack_file" -C "$TMP_DIR" "$PACKED_CLI_ENTRY" ||
+    fail "packed CLI artifact not found in $PACKAGE@$VERSION"
+
+  packed_cli="$TMP_DIR/$PACKED_CLI_ENTRY"
+  [ -f "$packed_cli" ] || fail "packed CLI artifact not found in $PACKAGE@$VERSION"
+  SOURCE_CLI="$packed_cli"
+}
+
+require_command shasum
+require_command node
+require_command sed
+
+resolve_source_cli
+source_cli="$SOURCE_CLI"
+[ -n "$source_cli" ] || fail "unable to resolve bundled CLI source"
+actual_sha=$(sha256_of "$source_cli")
+
+if [ "$actual_sha" != "$EXPECTED_SHA256" ]; then
+  fail "unexpected CLI SHA-256 for $source_cli: $actual_sha"
+fi
+
+mkdir -p "$INSTALL_DIR" "$BIN_DIR"
+cp "$source_cli" "$INSTALL_CLI"
+chmod 755 "$INSTALL_CLI"
+
+quoted_install_cli=$(shell_quote "$INSTALL_CLI")
+{
+  printf '%s\n' '#!/usr/bin/env sh'
+  printf 'DEFAULT_MARKDOWN_ENGINE_CLI=%s\n' "$quoted_install_cli"
+  printf '%s\n' 'MARKDOWN_ENGINE_CLI="${MARKDOWN_ENGINE_CLI:-$DEFAULT_MARKDOWN_ENGINE_CLI}"'
+  printf '%s\n' 'exec "${NODE_BINARY:-node}" "$MARKDOWN_ENGINE_CLI" "$@"'
+} > "$BIN_PATH"
+chmod 755 "$BIN_PATH"
+
+"${NODE_BINARY:-node}" "$INSTALL_CLI" --help >/dev/null
+
+printf 'Installed markdown-engine CLI: %s\n' "$INSTALL_CLI"
+printf 'Installed markdown-engine wrapper: %s\n' "$BIN_PATH"
+printf 'SHA-256: %s\n' "$actual_sha"

package/skills/profile-backed-markdown/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: profile-backed-markdown
+description: Validate Markdown files that declare a local markdown-engine validation profile in frontmatter.
+---
+
+# Profile-Backed Markdown
+
+Use this skill when a Markdown file contains frontmatter with `validationProfile`
+and you need deterministic profile validation before editing or handing off the
+file.
+
+## Workflow
+
+1. Run the bundled wrapper:
+
+```bash
+node scripts/validate-profile-backed-markdown.mjs --file /path/to/file.md
+```
+
+2. Treat stdout as the validator JSON source of truth. Do not infer pass/fail
+   from prose or repair notes.
+3. If validation fails, rerun with `--repair-brief` to emit compact repair
+   guidance on stderr while preserving validator JSON on stdout.
+4. Edit the Markdown file only when the user asked for repair. Do not edit
+   validation profiles unless explicitly requested.
+5. Rerun the wrapper after edits and require exit code `0` before reporting the
+   document clean.
+
+## Frontmatter Contract
+
+The wrapper reads a top-level frontmatter scalar:
+
+```yaml
+validationProfile: operational-spec
+```
+
+Profile names resolve to `assets/profiles/<validationProfile>.yaml` by default.
+The wrapper rejects absolute paths and parent-directory traversal so validation
+profiles stay within the local skill assets.
+
+## Bundled CLI
+
+The wrapper does not require a globally installed `markdown-engine` binary. It
+uses `MARKDOWN_ENGINE_CLI` when set, then checks for a local
+`scripts/markdown-engine-cli.mjs`, then falls back to the package-level
+`dist-bundled/markdown-engine-cli.mjs`.
+
+For a standalone skill folder, build and copy the bundled CLI artifact before
+distribution:
+
+```bash
+npm run build:cli:bundled
+cp dist-bundled/markdown-engine-cli.mjs skills/profile-backed-markdown/scripts/
+```

package/skills/profile-backed-markdown/assets/profiles/operational-spec.yaml

@@ -0,0 +1,98 @@
+syntaxVersion: markdown-engine.validation@v1
+documentVersion: 1.0.0
+rules:
+  - id: frontmatter.required
+    select:
+      target: document
+    assert:
+      frontmatterRequired:
+        fields:
+          - title
+          - owner
+          - status
+
+  - id: sections.required
+    select:
+      target: document
+    assert:
+      sectionsRequired:
+        order: strict
+        headings:
+          - Objective
+          - Context / Constraints
+          - Execution Plan
+          - Risk Register
+          - Handoff Links
+
+  - id: objective.text
+    select:
+      target: section
+      title: Objective
+    assert:
+      text:
+        contains: "Mission control"
+
+  - id: objective.length
+    select:
+      target: section
+      title: Objective
+    assert:
+      textLength:
+        min: 80
+        max: 180
+
+  - id: risk.table.columns
+    select:
+      target: table
+      section: Risk Register
+      header:
+        - ID
+        - Mitigation
+        - Status
+    assert:
+      tableColumnsRequired:
+        columns:
+          - ID
+          - Mitigation
+          - Status
+
+  - id: risk.ids.unique
+    select:
+      target: tableCell
+      section: Risk Register
+      tableHeader:
+        - ID
+        - Mitigation
+        - Status
+      column: ID
+    assert:
+      ids:
+        prefix: OPS-RISK
+        unique: true
+
+  - id: execution.must.count
+    select:
+      target: section
+      title: Execution Plan
+    assert:
+      textOccurrenceCount:
+        text: MUST
+        count: 2
+
+  - id: execution.list
+    select:
+      target: list
+      section: Execution Plan
+      ordered: false
+    assert:
+      text:
+        contains: "Validate profile"
+
+  - id: handoff.link
+    select:
+      target: link
+      section: Handoff Links
+      text: "handoff packet"
+      url: "./handoff-packet.md"
+    assert:
+      exists: true

package/skills/profile-backed-markdown/references/repair-brief.md

@@ -0,0 +1,14 @@
+# Repair Brief Contract
+
+`--repair-brief` emits a compact diagnostic summary on stderr and preserves the
+validator JSON result on stdout.
+
+Each diagnostic entry is derived from validator JSON only:
+
+- `ruleId`: the failing profile rule when present, otherwise `(none)`.
+- `message`: the validator diagnostic message.
+- `sourceRange`: the validator diagnostic range when present, otherwise
+  `unavailable`.
+
+The wrapper must not invent validation outcomes, synthesize missing diagnostics,
+or edit local profile assets.