preamble

Automated License & Metadata Generator for Codebases

Preamble automatically inserts and updates license headers, metadata, and file tracking information across your codebase. It ensures every file has a consistent preamble block, tracking file versions, sizes, and cryptographic hashes—helping maintain organization and integrity in large projects.

Features

• Auto-Inject Metadata – Adds license headers, UUIDs, file size, hash tracking, and versioning.
• You Design It – Write your preamble how you like, by drawing from lots of options like UUIDs, file size, hash tracking**, and versioning.
• One-Command Processing – Run on entire repositories with a single command.

Installation

Install Preamble globally or as a dev dependency:

npm install -D preamble

Run the CLI help command:

npx preamble --help

Usage

Preamble scans your codebase, identifies files, and injects metadata automatically.

Create a .preamble

Customize your metadata template. You can use any of the options shown here or just add your own variables unique per file. They self heal each time you update.

• {{GEN_PACKAGE_NAME}}
• @license
• Apache-2.0
• Copyright 2024 Alex Stevovich
• Licensed under the Apache License, Version 2.0 (the "License");
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at

• http://www.apache.org/licenses/LICENSE-2.0

• Unless required by applicable law or agreed to in writing, software
• distributed under the License is distributed on an "AS IS" BASIS,
• WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
• See the License for the specific language governing permissions and
• limitations under the License.
• @meta
• package_name: {{GEN_PACKAGE_NAME}}
• file_name: {{GEN_FILE_NAME}}
• purpose: {{PURPOSE}}
• @system
• generated_on: {{GEN_GENERATED_ON}}
• certified_version: {{GEN_CERTIFIED_VERSION}}
• file_uuid: {{GEN_FILE_UUID}}
• file_size: {{GEN_FILE_SIZE}}
• file_hash: {{GEN_FILE_HASH}}
• mast_hash: {{GEN_MAST_HASH}}
• generated_by: {{GEN_GENERATED_BY}}
• {{PREAMBLE_MARKER}}

Note The special marker {{PREAMBLE_MARKER}} is required to identify and update the correct block.

Apply Preamble to Your Codebase

Run the following command to inject metadata into your source files:

npx preamble --apply --dir ./src/

• apply → Enables preamble injection.
• dir → Defines the directory to scan (required).
• template → (Optional) Specify a custom template (defaults to ./.preamble).

Example: This will automatically insert/update preambles in all .js, .ts, .mjs files inside ./src/.

Template System

Preamble supports self-healing keys and auto-generated values.

Self-Healing Keys

• Any key written as key: {{KEY_NAME}} will persist across updates.

Example

purpose: {{PURPOSE}}

Generated Values

The template is offered many generated keys you can insert however you want

| Key | Description | | --------------------------- | ------------------------- | | {{GEN_FILE_NAME}} | Filename | | {{GEN_FILE_SIZE}} | File Size (Bytes) | | {{GEN_FILE_HASH}} | SHA-256 File Hash | | {{GEN_PACKAGE_NAME}} | Package Name | | {{GEN_FULL_YEAR}} | Current Year | | {{GEN_MAST_HASH}} | Metadata Hash | | {{GEN_CERTIFIED_VERSION}} | Package Version | | {{GEN_GENERATED_ON}} | Timestamp of Update | | {{GEN_GENERATED_BY} | outputs: preamble on npm! |

File Hashing & Version Tracking

Explain how if you use hash values file_hash mast_hash then the document will only update when either are changed.

Why Use Hashes?

Preamble can store a checksum hash of the current file version:

• file_hash → Hash of the entire file
• mast_hash → Hash of the metadata block

Update Behavior

✅ Files only update if the content or metadata changes.
✅ If the content is unchanged, Preamble skips updating (preventing unnecessary modifications).

License

Licensed under the Apache License 2.0.

Links

• GitHub: alexstevovich/preamble
• NPM Package: preamble