🚪 ostiary

Pre-push validation tool that catches merge conflicts and build failures before CI does

ostiary (from Latin "ostiarius" - doorkeeper) is a git workflow tool that keeps your code synced and validated. Run it manually to sync before starting work, or install as a pre-push hook to catch merge conflicts.

npm install --save-dev ostiary

What It Does

Ostiary automates the workflow of syncing with remote and validating your code:

# Instead of manually doing:
git fetch origin
git merge origin/main
npm run build
npm run test

# Just run:
ostiary

It fetches the latest changes from your remote, merges them into your current branch, and runs your validation commands (build, test, lint, etc.). If anything fails, you know immediately.

Why Ostiary?

Problem: You push your code, then wait for CI, only to find out it won't merge cleanly or breaks the build.

Solution: Install ostiary as a pre-push hook. It checks if your push will merge cleanly BEFORE you push.

Key Benefits

• ✅ Catches merge conflicts before you push
• ✅ Validates build/tests still pass after merging remote changes (no waiting for CI)
• ✅ Two modes: manual workflow tool OR automatic git hook

Installation

npm install --save-dev ostiary
npx ostiary init

The script will automatically:

• Detect your package manager (npm, pnpm, yarn, bun)
• Detect your git remote name
• Create .ostiary.json5 with sensible defaults

Optionally, add to package.json:

{
  "sripts": {
    "postinstall": "ostiary init || true"
  }
}

Postinstall script will not run on some conditions (useful in CI):

OSTIARY_SKIP=1 npm install
# or, in most CI, by default
CI=1 npm install

Usage

Manual Mode (Run When Needed)

After installation, run ostiary whenever you want to sync:

npx ostiary

Or, add it to your package.json:

{
  "scripts": {
    "ostiary": "ostiary"
  }
}

Git Hook Mode

You can use ostiary in git hooks to automatically check before pushing. Here's an example:

Using Husky

Husky - Git hooks made easy

# Install husky
npm install --save-dev husky
npx husky init

# Create pre-push hook
echo "ostiary" > .husky/pre-push
chmod +x .husky/pre-push

Now ostiary runs automatically before every push, catching merge conflicts and build failures before they reach CI.

What Happens

When you git push:

1. Git triggers the pre-push hook
2. Ostiary fetches and merges latest from remote
3. If merge conflicts → push is blocked, you fix locally
4. If commands fail → push is blocked, you fix locally
5. If everything passes → push proceeds

Benefits:

• Instant feedback (no waiting for CI)
• Prevents pushing code that won't merge
• Catches build/test failures locally
• Saves CI resources and time

Config File

Default .ostiary.json5:

{
  // Git remote to sync with
  origin: "origin",

  // Commands to run after merging
  // These validate that everything still works after sync
  commands: [
    // "npm run build",
    // "npm run test"
  ]
}

How It Works

1. Fetch - Gets latest changes from your remote branch
2. Check - Detects if there are any changes (exits early if not)
3. Merge - Merges remote changes into your current branch
4. Validate - Runs your validation commands sequentially
5. Success/Fail - Clear feedback on what happened

If any step fails, ostiary stops and shows you the error with helpful context.

Environment Variables

• CI - Skips postinstall initialization in CI environments
• OSTIARY_SKIP - Skips postinstall initialization

# Skip postinstall during install
# Any non-empty value will skip (including '0', 'false', etc.)
OSTIARY_SKIP=0 npm install
# or
CI=1 npm install
# or
OSTIARY_SKIP=nonempty ostiary

# all will skip

API Usage

Use ostiary programmatically in your Node.js scripts:

import { ostiary } from 'ostiary';

// Run the full sync + validate workflow
await ostiary('origin', ['npm run build', 'npm test'], false);

Help

ostiary - The code guard that: makes my life easier, kinda.

Usage:
  ostiary [command] [options]

  Running without any command will execute the 'run' command.
  It will load .ostiary.json5 from the current directory.

  Commands:
    init                        Initialize ostiary in current repository

    run                         Run ostiary in current repository
      [--origin <remote>]       Run ostiary with specified origin
      [--config <path>]         Use custom config file instead of .ostiary.json5
      
    setup                       Setup ostiary in current repository
      [--force, -f]             Force setup even if already initialized
    
    help, -h, --help            Show help for a command
    
    version, -v, --version      Show the version number

License

MIT

Contributing

• Report bugs via GitHub Issues
• Submit PRs for new features or fixes
• Share feedback and use cases

ostiary - Your doorkeeper. 🚪