npm package: @lasmedia/dev-scripts
Description: Collection of development scripts
Author: lasmedia
Latest version: 1.1.5

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

```bash
# 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`

```bash
# 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](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

```bash
# 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

```bash
# 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

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

### Using with yarn/npm

```bash
# 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

```markdown
# 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)

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

```bash
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](https://github.com/npryce/adr-tools) - Original ADR tools by Nat Pryce
- [Semantic Versioning](https://semver.org/) - Versioning specification
- [Architecture Decision Records](https://adr.github.io/) - ADR community resources

---

**Lightweight package** | **Zero runtime dependencies** | **Cross-platform compatible**