migrate 0.4.1

Generic file migration tool for applying ordered transformations to a project directory
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# migrate

Generic file migration tool for applying ordered transformations to a project directory. Migrations can be written in any language (bash, TypeScript, Python, etc.) using shebangs.

## Commands

```bash
migrate status                              # Show applied/pending migrations
migrate up                                  # Apply all pending migrations
migrate up --dry-run                        # Preview without applying
migrate up --baseline                       # Apply and create baseline at final version
migrate up --baseline --keep                # Apply and baseline without deleting files
migrate create <name>                       # Create new bash migration
migrate create <name> --template ts         # Create TypeScript migration
migrate create <name> --list-templates      # List available templates
migrate baseline <version>                  # Create baseline at specific version
migrate baseline <version> --dry-run        # Preview baseline changes
migrate baseline <version> --keep           # Baseline without deleting files
```

## Options

All commands accept:

- `-r, --root <path>` - Project root (default: `.`)
- `-m, --migrations <path>` - Migrations directory (default: `migrations`)

## Migration Format

Files: `XXXXX-name.{sh,ts,py,js,...}` where XXXXX is a 5-character base36 version.

**Version format:** `DDDMM` where:
- `DDD` = days since 2020-01-01 in base36 (~127 years of runway)
- `MM` = 10-minute slot of the day in base36 (144 slots/day)

Example: `1fb2g-add-config.sh` (created on day 1843 at slot 88 = ~14:40)

Migrations are executable files that receive context via environment variables:

```bash
MIGRATE_PROJECT_ROOT=/path/to/project      # Absolute path to project root
MIGRATE_MIGRATIONS_DIR=/path/to/migrations # Where migration files live
MIGRATE_ID=1fb2g-initial-setup             # Current migration ID (includes version)
MIGRATE_DRY_RUN=true|false                 # Whether this is a dry run
```

**Bash example:**
```bash
#!/usr/bin/env bash
set -euo pipefail
# Description: Initialize project structure

cd "$MIGRATE_PROJECT_ROOT"
mkdir -p config
```

**TypeScript example:**
```typescript
#!/usr/bin/env -S npx tsx
// Description: Add configuration file

import * as fs from 'fs/promises';
const projectRoot = process.env.MIGRATE_PROJECT_ROOT!;
await fs.writeFile(`${projectRoot}/config.json`, '{}');
```

## Architecture

- `src/main.rs` - CLI entry point (clap)
- `src/lib.rs` - Core types and public API
- `src/loader.rs` - Migration discovery
- `src/executor.rs` - Subprocess execution
- `src/state.rs` - History tracking (consolidated `history` file with applied migrations and baseline)
- `src/version.rs` - Base36 version generation and parsing
- `src/templates.rs` - Embedded migration templates
- `src/baseline.rs` - Baseline validation and file deletion
- `src/commands/` - CLI command implementations
  - `mod.rs` - Command module exports
  - `status.rs` - Status command (shows version summary)
  - `up.rs` - Up command
  - `create.rs` - Create command (generates time-based version)
  - `baseline.rs` - Baseline command (marks versions as applied)
- `templates/` - Template source files (bash.sh, typescript.ts, python.py, node.js, ruby.rb)

## Development

```bash
# Setup (enable git hooks, verify toolchain)
./scripts/setup

# Build and test
cargo nextest run      # Run tests
cargo build            # Build debug binary
cargo build --release  # Build release binary
cargo fmt              # Format code
cargo clippy           # Lint
```