@lasmedia/dev-scripts

A lightweight collection of development scripts for modern software teams. Ultra-portable, cross-platform tools for git workflow automation and architecture documentation.

🚀 Features

• 📅 Automated Git Tagging - Date-based semantic versioning with git-tag
• 📝 Architecture Decision Records (ADR) - Create and manage ADRs with adr
• 🌍 Cross-Platform - Works on macOS, Linux, and Windows (WSL)
• 📦 Ultra Lightweight - Minimal package size
• 🔧 Zero Dependencies - Pure bash scripts, no npm dependencies

📦 Installation

Local Project Installation

# Using npm
npm install @lasmedia/dev-scripts --save-dev

# Using yarn
yarn add @lasmedia/dev-scripts --dev

🛠️ Available Commands

git-tag - Automated Git Tagging

Creates automatic version tags using date-based semantic versioning in format: vYYYY.MM.DD.X

# Create a new version tag
git-tag

# Examples of generated tags:
# v2025.08.22.1  (first tag today)
# v2025.08.22.2  (second tag today)
# v2025.08.23.1  (first tag tomorrow)

Features:

• ✅ Automatic date-based versioning
• ✅ Incremental numbering for same-day releases
• ✅ Prevents duplicate tags on same commit
• ✅ Fetches remote tags before creating new ones

adr - Architecture Decision Records

Create and manage Architecture Decision Records following Michael Nygard's ADR format.

# Create a new ADR
adr new "Use PostgreSQL for primary database"

# Create ADR in custom directory
adr new "Implement microservices architecture" -d architecture/decisions

# Generate index of all ADRs
adr list

# Generate index in custom directory
adr list -d architecture/decisions

# Show help
adr --help

Features:

• ✅ Automatic numbering (1, 2, 3... not 0001, 0002)
• ✅ Template-based ADR generation
• ✅ Automatic index generation with links
• ✅ Custom directory support
• ✅ Reads titles directly from markdown files

📋 Usage Examples

Setting up ADRs in your project

# Create your first ADR
adr new "Use React for frontend framework"

# Create more ADRs
adr new "Choose PostgreSQL over MongoDB"
adr new "Implement REST API architecture"

# Generate a nice index page
adr list

This creates:

docs/adr/
├── 0001-use-react-for-frontend-framework.md
├── 0002-choose-postgresql-over-mongodb.md
├── 0003-implement-rest-api-architecture.md
└── index.md

Adding to package.json scripts

{
  "scripts": {
    "tag": "git-tag",
    "adr": "adr new",
    "adr:list": "adr list"
  }
}

Using with yarn/npm

# Using npm scripts
npm run adr "My Decision"
npm run tag

# Using yarn scripts
yarn adr "My Decision"
yarn tag

# Using npx directly
npx adr new "My Architecture Decision"
npx git-tag

📁 Generated File Structure

ADR Files

# 1. Use PostgreSQL for primary database

Date: 2025-08-22

## Status

Proposed

## Context

[Describe the context and problem statement, including the forces at play]

## Decision

[Describe the decision made and why it was chosen]

## Consequences

### Positive

- [List positive consequences]

### Negative

- [List negative consequences or trade-offs]

### Neutral

- [List neutral consequences or implementation details]

## Notes

[Any additional notes, links to discussions, related ADRs, etc.]

ADR Index (auto-generated)

# Architecture Decision Records

This document contains a list of all Architecture Decision Records (ADRs) for this project.

## ADR Index

- [1. Use PostgreSQL for primary database](0001-use-postgresql-for-primary-database.md)
- [2. Choose React for frontend](0002-choose-react-for-frontend.md)
- [3. Implement REST API](0003-implement-rest-api.md)

## About ADRs

Architecture Decision Records (ADRs) are documents that capture important architectural decisions made during the project development.

We follow the ADR format proposed by Michael Nygard in [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

🔧 Configuration

Custom ADR Directory

By default, ADRs are created in docs/adr/. You can specify a custom directory:

adr new "My Decision" -d architecture/decisions
adr list -d architecture/decisions

Template Customization

ADR templates are included in the package and automatically used. The templates follow the standard ADR format with sections for Context, Decision, and Consequences.

🌍 Platform Compatibility

Platform	git-tag	adr	Status
macOS	✅	✅	Fully supported
Linux	✅	✅	Fully supported
Windows WSL	✅	✅	Fully supported
Windows Git Bash	⚠️	⚠️	Partial support

🤝 Contributing

Contributions are welcome! This project focuses on:

• Simplicity - Keep tools simple and focused
• Portability - Must work across platforms
• Lightweight - Minimal dependencies and size
• Standards - Follow established conventions (ADR format, semantic versioning)

📜 License

MIT © las media

🔗 Related Tools

• adr-tools - Original ADR tools by Nat Pryce
• Semantic Versioning - Versioning specification
• Architecture Decision Records - ADR community resources

---

Lightweight package | Zero runtime dependencies | Cross-platform compatible