Scripts.md

Scripts

This document describes the CLI helper scripts available in the /scripts directory.

Overview

Script	Purpose
create-migration.sh	Entity Framework Core migration management
update-tabler.sh	Update Tabler UI framework assets

create-migration.sh

A helper script for managing Entity Framework Core migrations.

Location

scripts/create-migration.sh

Prerequisites

• .NET SDK 9.0.300+
• EF Core CLI tools installed globally

Install EF Core tools if needed:

dotnet tool install --global dotnet-ef

Usage

./scripts/create-migration.sh <MigrationName> [--apply]
./scripts/create-migration.sh --remove

Commands

Create a New Migration

./scripts/create-migration.sh AddPaymentIndex

This creates a new migration file in src/OpenCashFlow.Shared/Data/Migrations/.

Output:

Creating migration: AddPaymentIndex
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

Create and Apply a Migration

./scripts/create-migration.sh AddPaymentIndex --apply

This creates the migration and immediately applies it to the database.

Output:

Creating migration: AddPaymentIndex
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
Applying migration...
Applying migration '20260124150000_AddPaymentIndex'.
Done.

Remove the Last Migration

./scripts/create-migration.sh --remove

This removes the most recent unapplied migration.

Output:

Removing last migration...
Removing migration '20260124150000_AddPaymentIndex'.
Done.

Configuration

The script uses these hardcoded paths:

PROJECT="src/OpenCashFlow.Shared/OpenCashFlow.Shared.csproj"
STARTUP_PROJECT="src/OpenCashFlow.API/OpenCashFlow.API.csproj"
CONTEXT="ApplicationDbContext"
OUTPUT_DIR="Data/Migrations"

Equivalent Manual Commands

If you prefer to run commands manually:

Create migration:

dotnet ef migrations add <MigrationName> \
  --project src/OpenCashFlow.Shared/OpenCashFlow.Shared.csproj \
  --startup-project src/OpenCashFlow.API/OpenCashFlow.API.csproj \
  --context ApplicationDbContext \
  --output-dir Data/Migrations

Apply migrations:

dotnet ef database update \
  --project src/OpenCashFlow.Shared/OpenCashFlow.Shared.csproj \
  --startup-project src/OpenCashFlow.API/OpenCashFlow.API.csproj \
  --context ApplicationDbContext

Remove last migration:

dotnet ef migrations remove \
  --project src/OpenCashFlow.Shared/OpenCashFlow.Shared.csproj \
  --startup-project src/OpenCashFlow.API/OpenCashFlow.API.csproj \
  --context ApplicationDbContext

Migration Naming Conventions

Use clear, descriptive names:

Pattern	Example	Use Case
Add<Entity>	AddCashLedger	New table
Add<Entity><Column>	AddPaymentDescription	New column
Remove<Entity><Column>	RemoveUserMiddleName	Drop column
Rename<Old>To<New>	RenameEmailToContactEmail	Rename column
Add<Entity>Index	AddPaymentDateIndex	New index
Update<Entity>	UpdateCompanySchema	Multiple changes

Troubleshooting

"Build failed"

Ensure the projects compile successfully:

dotnet build src/OpenCashFlow.Shared/OpenCashFlow.Shared.csproj
dotnet build src/OpenCashFlow.API/OpenCashFlow.API.csproj

"Unable to create DbContext"

Check that:

1. The connection string is set in environment or appsettings.json
2. PostgreSQL is running
3. The database exists

"Migration already exists"

Migration names must be unique. Use a different name or remove the existing migration first.

---

update-tabler.sh

A script to update the Tabler UI framework to the latest version.

Location

scripts/update-tabler.sh

Purpose

Downloads and extracts the latest Tabler release to /templates/tabler/core/.

Usage

./scripts/update-tabler.sh

What It Does

1. Downloads the latest Tabler release from GitHub
2. Extracts to /templates/tabler/core/
3. Copies relevant assets to src/OpenCashFlow.App/wwwroot/vendor/tabler/

Manual Update Process

If the script doesn't work, update manually:

1. Download from https://github.com/tabler/tabler/releases
2. Extract the archive
3. Copy CSS files to wwwroot/vendor/tabler/css/
4. Copy JS files to wwwroot/vendor/tabler/js/
5. Copy fonts to wwwroot/vendor/tabler/fonts/

Tabler Assets Structure

wwwroot/vendor/tabler/
├── css/
│   ├── tabler.min.css
│   └── tabler-vendors.min.css
├── js/
│   ├── tabler.min.js
│   └── tabler-vendors.min.js
└── fonts/
    └── (icon fonts)

---

Script Permissions

Ensure scripts are executable:

chmod +x scripts/create-migration.sh
chmod +x scripts/update-tabler.sh

Adding New Scripts

When adding new scripts:

1. Place them in the /scripts directory
2. Use .sh extension for bash scripts
3. Add a shebang line: #!/bin/bash
4. Make them executable
5. Document them in this file

Script Template

#!/bin/bash

# Script Name: my-script.sh
# Purpose: Brief description of what this script does
# Usage: ./scripts/my-script.sh [arguments]

set -e  # Exit on error

# Configuration
VARIABLE="value"

# Functions
function show_usage() {
    echo "Usage: $0 [arguments]"
    echo "  argument1  Description of argument 1"
    echo "  --help     Show this help message"
}

# Main logic
if [ "$1" == "--help" ]; then
    show_usage
    exit 0
fi

echo "Executing script..."
# Your commands here

echo "Done."

CI/CD Scripts

For CI/CD automation, see .github/workflows/. The GitHub Actions workflows handle:

• Building and testing on PR/push
• Creating release artifacts
• Deploying to staging/production

These are not in /scripts as they're GitHub-specific configurations rather than developer-run scripts.