added gen.js section

2026-09-09 11:22:07 -06:00
parent c2e3e18fda
commit fdcd6d8ab7
1 changed files with 30 additions and 1 deletions
@@ -1,8 +1,37 @@
 # README

-* emit.js will scaffold a dir or update files that are already there
 * gen.js is the build script that builds to the target dir
 * serve.js is a local server for your cards interface
+* emit.js will scaffold a dir or update files that are already there
+
+
+# gen.mjs
+
+`gen.mjs` is the manifest generator and identifier minting engine. It scans markdown files within a source directory, ensures every card possesses a stable UUID v7 identifier, and compiles an auto-generated JavaScript manifest module exposing the card collection and tag vocabulary.
+
+## Usage
+
+```bash
+node engine/gen.mjs [--src <dir>] [--target <file>]
+```
+
+* **`--src <dir>`**: The source directory containing the markdown cards to process (defaults to `content`).
+* **`--target <file>`**: The output file path for the generated manifest module (defaults to `_manifest.js`).
+
+## Core Principles
+
+* **UUID v7 Minting & Auditing**: Scans each `.md` file for an embedded HTML comment ID (`<!-- id: <uuid> -->`). If absent, it mints a new time-ordered UUID v7 and appends it to the bottom of the card. If a duplicate ID collision is detected across files, it automatically remints a fresh UUID in place.
+* **Metadata Extraction**: Parses YAML frontmatter blocks within the markdown cards to automatically extract and aggregate a unified, sorted tag vocabulary.
+* **Manifest Compilation**: Employs static relative module specifiers to build an indexed `CARDS` array and a `TAGS` vocabulary array, exporting them for build-time and boot-time consumption while strictly marking the output as auto-generated.
+
+## Workflow Execution
+
+1. **Argument Resolution**: Resolves command-line overrides for the source directory (`--src`) and target output (`--target`), falling back to default values.
+2. **File Discovery**: Filters the source directory for all files ending in `.md` and sorts them alphabetically.
+3. **ID Reconciliation**: Iterates through each file to read and validate its ID token against the `ID_RE` pattern. Minting or collision handling writes updates back to disk immediately if modifications occur.
+4. **Tag Parsing**: Extracts comma-delimited items from frontmatter `tags: [...]` declarations across all discovered markdown files to populate the global tag set.
+5. **Manifest Emission**: Generates static ES module imports for every markdown card, maps out metadata items (slug, id, imported content reference), serializes the sorted tag list, and writes the complete bundle to the target path.
+

 # emit.mjs