preamble/README.md

Automated License & Metadata applicators for Codebases.

# 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:

```js
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

```txt
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](https://github.com/alexstevovich/preamble)
- **NPM Package**: [preamble](https://www.npmjs.com/package/preamble)