shipmast/README.md

Automated License & Metadata applicators for Codebases.

# shipmast

> **archetype:**  Automated License & Metadata Generator for Codebases
> **dev**: [https://github.com/alexstevovich/shipmast-node](https://github.com/alexstevovich/shipmast-node)
> **cli**: [https://github.com/alexstevovich/shipmast-cli-node](https://github.com/alexstevovich/shipmast-cli-node)


**shipmast** inserts and updates license headers, metadata, and file tracking information across your codebase. 

## Features

- **Automated License & Metadata Injection** – Adds customizable info blocks to your files.
- **Customizable Templates** – Define exactly how metadata should be formatted.
- **Bulk Processing** – Update entire repositories with a single command.
- **Self-Healing Data** – Automatically maintains file-specific metadata across updates.

## Installation


```sh
npm install -D shipmast
```
The `-D` flag is recommended as **shipmast** is typically used in development.


## Usage

### Importing Shipmast

```js
import shipmast from  'shipmast';
```

### Applying Metadata to a Single File

To inject metadata into a file programmatically:

```js
import fs from  'fs/promises';
import shipmast from  'shipmast';

const content = await fs.readFile('./src/example.js', 'utf8');
const template = `*******************************
File: {{$file_path_relative}}
Generated On: {{$generated_on_iso}}
File UUID: {{$file_uuid}}
Generated By: {{$generated_by}}
*******************************`;

const { result, updated } = await shipmast.applyTemplate(content, template);
if (updated) {
await fs.writeFile('./src/example.js', result, 'utf8'); 
console.log('✅ Metadata applied.');
} 
else { console.log('ℹ️ No changes needed.');
} 
```

### Applying Metadata to Multiple Files

To apply metadata across multiple files:

```js
import shipmast from  'shipmast';
const template = `*******************************
File: {{$file_path_relative}}
Generated On: {{$generated_on_iso}}
File UUID: {{$file_uuid}}
Generated By: {{$generated_by}}
*******************************`;

await shipmast.applyTemplateGlob('./src/**/*.js',template) 
```

### Removing Shipmast Metadata

To remove shipmast metadata from a single file:

```js
import fs from  'fs/promises';
import shipmast from  'shipmast';

const content = await fs.readFile('./src/example.js', 'utf8');
const cleanedContent = shipmast.remove(content);
await fs.writeFile('./src/example.js', cleanedContent, 'utf8');
console.log('✅ Metadata removed.');` 
```

To remove shipmast metadata from multiple files:

```js
await shipmast.removeGlob('./src/**/*.js');
```


### Create a `.shipmast` Template

Customize your shipmast template. Use predefined keys or add your own. Data automatically updates while preserving custom fields.

```txt
********************************************
 shipmast

- Copyright 2000-{{$year_full}} Example Name
 
 @meta
 
 package_name: shipmast
 file_name: {{$file_path_relative}}
 purpose: {{purpose}}
   
 @system
 
 generated_on: {{$generated_on_iso}}
 file_uuid: {{$file_uuid}}
 file_size: {{$file_size_bytes}}
 file_hash: {{$file_hash}}
 mast_hash: {{$mast_hash}}
 generated_by: {{$generated_by}}
************************************* 
```

## Template System

Shipmast 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

Shipmast provides automatically generated metadata keys:

| Key                     | Description               |
|-------------------------|--------------------------|
| `{{$file_path_relative}}` | Relative file path       |
| `{{$file_size_bytes}}`    | File size in bytes       |
| `{{$file_hash}}`          | SHA-256 file hash        |
| `{{$year_full}}`          | Current year             |
| `{{$mast_hash}}`          | Metadata block hash      |
| `{{$generated_on_iso}}`   | Timestamp of update      |
| `{{$generated_by}}`       | Outputs: "shipmast on npm" |

## File Hashing & Version Tracking

Shipmast maintains hash values to track changes in files and metadata.

### Why Use Hashes?

Shipmast stores checksum hashes to determine when updates are needed:

-   `**file_hash**` → Hash of the **entire file**
    
-   `**mast_hash**` → Hash of the **metadata block**
    

#### Update Behavior

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

## Removing Shipmast Blocks

To remove shipmast metadata from a file:

```
shipmast --remove ./src/**/*.js
```

-   `**--remove**` → Deletes all shipmast blocks from matching files.
    
-   `**--dryRun**` → Preview changes before applying them.


## **Links**
I provide a cli interface for shipyard here:
**shipmast-cli**: [(https://github.com/alexstevovich/shipmast-cli](https://github.com/alexstevovich/shipmast-cli)

## Development Homepage

- **Development**: [https://github.com/alexstevovich/shipmast](https://github.com/alexstevovich/shipmast)
- **NPM Package**: [https://www.npmjs.com/package/shipmast](https://www.npmjs.com/package/shipmast)

[https://github.com/alexstevovich/wellwish-node](https://github.com/alexstevovich/wellwish-node)

## License

Licensed under the Apache License 2.0.