@jasonbelmonti/markdown-engine 3.0.0 → 3.1.1

package/docs/contracts/api.md

@@ -22,6 +22,7 @@ The package root exports the API functions, helpers, and types from `src/api/**`
 - `validateAnnotations(document, annotations)`
 - `parseValidationProfile(input, options?)`
 - `validateWithProfile(document, profile, options?)`
+- `validateDocumentSet(entries, options?)`
 
 The package root also exports the public result, document, diagnostic, config,
 and function types declared in `src/api/**`.
@@ -249,6 +250,64 @@ defaults, so an omitted `documentVersion` and an explicit matching
 `documentVersion` produce the same profile hash for the same document version
 and rules.
 
+## `validateDocumentSet`
+
+Signature:
+
+```ts
+validateDocumentSet(
+  entries: readonly ValidateDocumentSetEntry[],
+  options?: ValidateDocumentSetOptions,
+): ValidateDocumentSetResult
+```
+
+`validateDocumentSet` is a pure aggregate API for caller-supplied Markdown
+documents and caller-supplied validation profiles. Each entry contains:
+
+- `path`: caller-owned document path or stable identifier
+- `markdown`: Markdown text to parse and normalize
+- `profile`: YAML profile text, JSON-safe profile data, or parsed
+  `ValidationProfile`
+- `profilePath`: optional caller-owned profile path or stable identifier for
+  profile diagnostics
+
+The function processes entries in the supplied order and returns `entries` in
+that same order. It does not read directories, expand globs, watch files, write
+persistent state, add CLI behavior, classify OKF paths, or choose profiles for
+callers. Consumers own discovery, routing, and IO.
+
+For OKF-style bundles, `validateDocumentSet` stays a generic aggregation API.
+Callers must classify each path before calling the function and provide the
+profile for that caller-classified role. A non-reserved concept document can use
+a concept profile that requires `type` frontmatter, the bundle-root `index.md`
+can use a root-index profile that accepts the `okf_version: "0.1"` exception, a
+non-root `index.md` can use a no-frontmatter profile, and `log.md` can use a
+log profile that checks date headings.
+
+The API does not infer those roles from paths.
+
+`ValidateDocumentSetOptions` forwards supported document normalization and
+validation options:
+
+- `documentVersion`
+- `preserveSourceLocations`
+- `includeEvidence`
+
+Each `ValidateDocumentSetEntryResult` contains:
+
+- `path` and optional `profilePath`
+- `parseDiagnostics`
+- `normalizationDiagnostics`
+- `profileDiagnostics`
+- `validationDiagnostics`
+- aggregate entry `diagnostics`
+- `validationResult` when profile parsing succeeds without error-severity
+  diagnostics
+
+Profile-stage failures on one entry do not stop later entries from processing.
+The aggregate `valid` field is `false` when any aggregate diagnostic has
+severity `error`; otherwise it is `true`.
+
 ## `serialize`
 
 Signature:
@@ -260,6 +319,7 @@ serialize(
     | NormalizeResult
     | ValidationResult
     | DeclarativeValidationResult
+    | ValidateDocumentSetResult
     | EngineDocument
     | AnnotationValidationResult,
   options?: SerializeOptions,

package/docs/contracts/declarative-validation.md

@@ -1,11 +1,13 @@
 # Declarative Validation Contract
 
 Status: package 3.0.0, v1 profile syntax with v2 Conditional V2, document contract 1.0.0
-Last updated: 2026-06-05
+Last updated: 2026-06-15
 Current v2 surface: flat-rule result/evidence shell, ID count-bound schema and
 runtime evaluator contract, plus `tableColumnCoverage` schema, compiled-plan,
-and runtime evaluator contract, grouped rule runtime contract, and rule-level
-`when` schema, matcher, public skipped-rule result, skipped counts, and evidence
+and runtime evaluator contract, `frontmatterShape` schema, compiled-plan, and
+runtime evaluator contract, `textFormat` schema, compiled-plan, and runtime
+evaluator contract, grouped rule runtime contract, and rule-level `when`
+schema, matcher, public skipped-rule result, skipped counts, and evidence
 cloning contract.
 
 This document defines the public declarative validation contract for
@@ -25,8 +27,11 @@ optional rule-level `when`. The admitted v2 path exposes the result and evidence
 shell needed to distinguish assertion, grouped, and skipped evaluation output
 from v1 output, plus the ID count-bound schema, compiled-plan, and runtime
 evaluator contract; the `tableColumnCoverage` schema, compiled-plan, and
-runtime evaluator contract; and the `when` schema plus private compiled-plan and
-matcher contract. Matched applicability continues into normal rule evaluation.
+runtime evaluator contract; the `frontmatterShape` schema, private
+compiled-plan, and runtime evaluator contract; the `textFormat` schema,
+private compiled-plan, and runtime evaluator contract; and the `when` schema
+plus private compiled-plan and matcher contract. Matched applicability
+continues into normal rule evaluation.
 Non-matching applicability returns a public skipped rule result with
 `status: "skipped"`, `passed: true`, `evaluation.kind: "skipped"`,
 `reason: "whenNotMatched"`, `skippedRuleCount`, no top-level diagnostics, and a
@@ -53,6 +58,11 @@ validateWithProfile(
   profile: ValidationProfile,
   options?: DeclarativeValidationOptions,
 ): DeclarativeValidationResult
+
+validateDocumentSet(
+  entries: readonly ValidateDocumentSetEntry[],
+  options?: ValidateDocumentSetOptions,
+): ValidateDocumentSetResult
 ```
 
 Compiled declarative validation plans are internal. They are not exported from
@@ -79,13 +89,16 @@ syntaxVersion: markdown-engine.validation@v2
 This release recognizes v2 as a distinct syntax version at profile admission,
 admits ID count bounds at the schema, compiled-plan, and runtime evaluator
 layers, admits `tableColumnCoverage` at the schema, internal compiled-plan, and
-runtime evaluator layers, admits non-recursive grouped rules at the schema,
-compiled-plan, and runtime evaluator layers, and admits optional rule-level
-`when` at the schema, internal compiled-plan, and matcher layers. Matching
-`when` rules continue through normal flat or grouped evaluation and do not add a
-public `when` field to the evaluated rule result. Non-matching `when` rules are
-not evaluated; they return the public skipped-rule result shape, increment
-`skippedRuleCount`, and leave `evaluatedRuleCount` unchanged.
+runtime evaluator layers, admits `frontmatterShape` at the schema, internal
+compiled-plan, and runtime evaluator layers, admits `textFormat` at the schema,
+internal compiled-plan, and runtime evaluator layers, admits non-recursive
+grouped rules at the schema, compiled-plan, and runtime evaluator layers, and
+admits optional rule-level `when` at the schema, internal compiled-plan, and
+matcher layers.
+Matching `when` rules continue through normal flat or grouped evaluation and do
+not add a public `when` field to the evaluated rule result. Non-matching `when`
+rules are not evaluated; they return the public skipped-rule result shape,
+increment `skippedRuleCount`, and leave `evaluatedRuleCount` unchanged.
 
 The admitted v1/v2 flat vocabulary is closed. Unknown profile keys, rule keys,
 selector keys, known assertion keys, and nested assertion keys emit
@@ -207,8 +220,8 @@ emit `profile.config.invalidShape`.
 
 Rule-level `when` is allowed only on v2 rules. Branch-level `when` remains
 unsupported. V1 profiles preserve the original flat rule authoring contract;
-grouped `anyOf` / `allOf`, ID count bounds, `tableColumnCoverage`, and
-rule-level `when` are v2 additions.
+grouped `anyOf` / `allOf`, ID count bounds, `tableColumnCoverage`,
+`frontmatterShape`, `textFormat`, and rule-level `when` are v2 additions.
 
 Profile values must be JSON-safe data properties after YAML materialization.
 Functions, accessors, proxies, cyclic structures, sparse arrays, `undefined`
@@ -300,6 +313,15 @@ interface DeclarativeAssertion {
     };
     require: "everySourceId";
   };
+  frontmatterShape?: {
+    presence?: "required" | "forbidden";
+    fields?: readonly {
+      field: string;
+      required?: true;
+      valueType?: "string" | "number" | "boolean" | "array" | "object" | "null";
+      nonEmpty?: true;
+    }[];
+  };
   text?: {
     contains?: string;
     excludes?: readonly string[];
@@ -312,6 +334,9 @@ interface DeclarativeAssertion {
     min?: number;
     max?: number;
   };
+  textFormat?: {
+    format: "isoDate";
+  };
   frontmatterRequired?: {
     fields: readonly string[];
   };
@@ -335,9 +360,11 @@ Selector/assertion compatibility is part of the public contract:
 | `ids` | all supported selector targets |
 | `references` | `document` |
 | `tableColumnCoverage` | `document` |
+| `frontmatterShape` | `document` |
 | `text` | all supported selector targets |
 | `textOccurrenceCount` | all supported selector targets |
 | `textLength` | all supported selector targets |
+| `textFormat` | all supported selector targets |
 | `frontmatterRequired` | `document` |
 
 Incompatible supported selector/assertion pairs emit
@@ -378,6 +405,35 @@ target section do not satisfy coverage. Missing target sections, missing target
 columns, and missing target-column IDs emit deterministic validation diagnostics
 source-grounded to the source ID when source evidence is available.
 
+For v2 profiles, `frontmatterShape` is admitted as a flat-rule schema and
+internal compiled-plan assertion. It is compatible only with a `document`
+selector because frontmatter is document metadata. `presence` is optional and
+must be exactly `"required"` or `"forbidden"` when provided. `fields` is an
+optional non-empty array of field constraints. Each field constraint has a
+required non-empty `field` name and must include at least one effective
+constraint: `required: true`, `valueType`, or `nonEmpty: true`. Field names
+within one `frontmatterShape.fields` array must be unique. `valueType` must be
+one of `"string"`, `"number"`, `"boolean"`, `"array"`, `"object"`, or `"null"`.
+`nonEmpty: true` is a string predicate; when it is combined with `valueType`,
+`valueType` must be `"string"`. `presence: "forbidden"` cannot be combined with
+`fields`.
+
+Runtime evaluation treats frontmatter as present when
+`document.frontmatter !== undefined`. `presence: "required"` fails absent
+frontmatter with `profile.validation.frontmatterMissing`.
+`presence: "forbidden"` fails any present frontmatter value, including empty
+frontmatter, with `profile.validation.frontmatterForbidden`. Field constraints
+evaluate only top-level frontmatter fields and do not coerce values. A required
+field that is absent, or any required field on non-object frontmatter, emits
+`profile.validation.frontmatterFieldMissing`. Optional fields are ignored when
+absent. `valueType` checks distinguish `"string"`, finite `"number"`,
+`"boolean"`, `"array"`, plain `"object"`, and `"null"` values and emit
+`profile.validation.frontmatterFieldTypeMismatch` on mismatch. `nonEmpty: true`
+requires a present field value to be a non-empty string and emits
+`profile.validation.frontmatterFieldEmpty` when that predicate fails. When
+`valueType: "string"` and `nonEmpty: true` are combined, a non-string value
+emits the type-mismatch diagnostic without a duplicate empty-string diagnostic.
+
 `text` must include `contains` or a non-empty `excludes` array.
 `textOccurrenceCount.count` is a finite number and counts non-overlapping
 literal occurrences per selected target.
@@ -386,10 +442,22 @@ integers, `min` must be less than or equal to `max` when both are present, and
 evaluation uses JavaScript string `.length` for each selected target's
 normalized text.
 
+For v2 profiles, `textFormat` is admitted as a flat-rule schema and internal
+compiled-plan assertion. `textFormat.format` must be exactly `"isoDate"`;
+custom formats, locale options, regex-like formats, profile-supplied patterns,
+and additional `textFormat` members are unsupported. Runtime evaluation checks
+each selected target's normalized text as an exact real calendar date in
+`YYYY-MM-DD` form. Valid dates such as `2026-06-14` and leap dates such as
+`2024-02-29` pass. Non-dates, invalid calendar dates, timestamps, partial
+dates, and strings with extra text fail with
+`profile.validation.assertionFailed`. The evaluator does not compile
+profile-supplied regular expressions, call `Date.parse`, perform locale
+parsing, or implement date ordering.
+
 Empty selector results produce `profile.validation.emptySelection` for exists,
-table, ID, reference, text, occurrence, and text-length assertions.
-Document-scoped required-section and required-frontmatter assertions evaluate
-against the document.
+table, ID, reference, text, occurrence, text-length, and text-format
+assertions. Document-scoped required-section, required-frontmatter, and
+frontmatter-shape assertions evaluate against the document.
 
 ## Diagnostics
 
@@ -418,9 +486,13 @@ diagnostic can still leave the aggregate `valid` value `true`.
 | `profile.compile.unsupportedAssertion` | `error` | Parsed YAML or JSON-safe `assert` input contains an unsupported first-level assertion member that does not have unsupported-key precedence. |
 | `profile.compile.incompatibleSelectorAssertion` | `error` | A supported selector target is paired with an incompatible supported assertion. |
 | `profile.validation.emptySelection` | Rule severity | A rule cannot evaluate because its selector matches no applicable target. |
-| `profile.validation.assertionFailed` | Rule severity | A supported assertion evaluates and fails without a more specific diagnostic code, including missing table columns, exact occurrence-count mismatches, and text-length bound failures. |
+| `profile.validation.assertionFailed` | Rule severity | A supported assertion evaluates and fails without a more specific diagnostic code, including missing table columns, exact occurrence-count mismatches, text-length bound failures, and text-format `isoDate` failures. |
 | `profile.validation.duplicateId` | Rule severity | An `ids.unique` assertion finds repeated IDs. |
+| `profile.validation.frontmatterForbidden` | Rule severity | A `frontmatterShape` assertion with `presence: "forbidden"` finds present frontmatter. |
+| `profile.validation.frontmatterFieldEmpty` | Rule severity | A frontmatter field configured with `nonEmpty: true` is not a non-empty string. |
 | `profile.validation.frontmatterFieldMissing` | Rule severity | A required frontmatter field is absent. |
+| `profile.validation.frontmatterFieldTypeMismatch` | Rule severity | A frontmatter field value does not match the configured `frontmatterShape.fields[].valueType` without coercion. |
+| `profile.validation.frontmatterMissing` | Rule severity | A `frontmatterShape` assertion with `presence: "required"` finds absent frontmatter. |
 | `profile.validation.idCountTooHigh` | Rule severity | Unique ID count after filtering is higher than `ids.maxCount`. |
 | `profile.validation.idCountTooLow` | Rule severity | Unique ID count after filtering is lower than `ids.minCount`. |
 | `profile.validation.referenceMissing` | Rule severity | A source ID is absent from a required target section. |
@@ -552,8 +624,8 @@ serialization of the resolved `ValidationProfile` after applying the resolved
 `documentVersion` and an explicit matching `documentVersion` therefore produce
 the same profile hash for the same document version and rules.
 
-`engineVersion` records the package version that produced the evidence. In the
-3.0 release line this is `"3.0.0"` even though `documentVersion` remains
+`engineVersion` records the package version that produced the evidence. This
+matches the package metadata version even though `documentVersion` remains
 `"1.0.0"`.
 
 Raw Markdown bytes, raw YAML bytes, YAML comments, caller file paths, and
@@ -665,8 +737,21 @@ rules:
           exists: true
 ```
 
-The v1 profile above continues to emit the v1 validation-result shape. The v2
-profile above emits syntax-versioned v2 result metadata with
+```yaml
+# v2 date-heading profile: validates exact ISO date heading text.
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: log.date-heading
+    select:
+      target: heading
+      depth: 2
+    assert:
+      textFormat:
+        format: isoDate
+```
+
+The v1 profile above continues to emit the v1 validation-result shape. V2
+profiles emit syntax-versioned v2 result metadata with
 `evaluatedRuleCount` and `skippedRuleCount`; v2 rule results include `status`
 and `evaluation`. The CLI does not add a second discriminator for v2; consumers
 branch on
@@ -778,6 +863,60 @@ rules:
           exists: true
 ```
 
+### OKF v0.1 Hard-Validation Profile Composition
+
+`markdown-engine` does not ship a built-in OKF validator. Consumers that want to
+validate OKF v0.1 hard conformance compose generic declarative-validation
+profiles and route documents to those profiles themselves. The caller owns
+bundle traversal, path classification, IO, and role selection before invoking
+`validateDocumentSet`.
+
+The packaged OKF proof under
+`fixtures/declarative-validation/examples/okf-v0.1/**` uses four generic
+profiles:
+
+| Caller-classified role | Example profile | Generic checks |
+| --- | --- | --- |
+| Concept document | `profiles/concept.yaml` | `frontmatterShape` requires parseable frontmatter with a non-empty string `type`. |
+| Bundle-root `index.md` | `profiles/root-index.yaml` | `frontmatterShape` accepts a non-empty string `okf_version` when root version frontmatter is present. |
+| Non-root `index.md` | `profiles/non-root-index.yaml` | `frontmatterShape` forbids frontmatter on directory index files. |
+| `log.md` | `profiles/log.yaml` | `textFormat` checks level-2 log headings as real `YYYY-MM-DD` dates. |
+
+Concept validation applies only to non-reserved concept documents. Reserved
+`index.md` and `log.md` files are not routed through the concept profile and do
+not fail merely because they lack concept `type` frontmatter. The bundle-root
+`index.md` may carry the OKF version exception `okf_version: "0.1"` through the
+root-index profile; non-root `index.md` files use the non-root index profile and
+forbid frontmatter. `log.md` is validated as a log with `textFormat`, not as a
+concept document.
+
+A caller-owned routing layer can classify entries by path and choose the
+matching profile before validation:
+
+```ts
+const entries = bundleMarkdownFiles.map((file) => {
+  const role = classifyOkfPath(file.path);
+
+  return {
+    path: file.path,
+    markdown: file.markdown,
+    profile: profilesByRole[role],
+    profilePath: profilePathsByRole[role],
+  };
+});
+
+const result = validateDocumentSet(entries, {
+  documentVersion: "1.0.0",
+  includeEvidence: true,
+});
+```
+
+This composition proves hard OKF conformance only. It does not add CLI
+traversal, an OKF adapter, runtime OKF semantics, directory watching, bundle
+discovery, link checking, unknown-type rejection, optional metadata quality
+checks, or rejection of missing optional `index.md` files. It also does not add
+engine-owned path classification.
+
 CLI invocation:
 
 ```sh

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": "3.0.0",
+  "version": "3.1.1",
   "description": "Deterministic Markdown parsing and validation engine package.",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,7 @@
   "files": [
     "dist",
     "dist-bundled",
+    "scripts/install-markdown-engine-cli.sh",
     "skills",
     "docs/contracts",
     "fixtures/declarative-validation/examples",
@@ -69,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 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: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/**\"",

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env sh
+set -eu
+
+VERSION="3.1.1"
+PACKAGE="@jasonbelmonti/markdown-engine"
+EXPECTED_SHA256="8c7ff572765cbdc6c38b94de52d69709f583ee7b4d2b7e25ba6be8c92125addf"
+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"