shipmast

archetype: Automated License & Metadata Generator for Codebases dev: https://github.com/alexstevovich/shipmast-node cli: 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

npm install -D shipmast

The -D flag is recommended as shipmast is typically used in development.

Usage

Importing Shipmast

import shipmast from  'shipmast';

Applying Metadata to a Single File

To inject metadata into a file programmatically:

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:

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:

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:

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.

********************************************
 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

Development Homepage

• Development: https://github.com/alexstevovich/shipmast
• NPM Package: https://www.npmjs.com/package/shipmast

https://github.com/alexstevovich/wellwish-node

License

Licensed under the Apache License 2.0.