# @bungres/kit

[![npm version](https://img.shields.io/npm/v/@bungres/kit.svg)](https://www.npmjs.com/package/@bungres/kit)
[![license](https://img.shields.io/npm/l/@bungres/kit.svg)](https://github.com/aniket/bungres/blob/main/LICENSE)

CLI toolkit for [`@bungres/orm`](https://www.npmjs.com/package/@bungres/orm) — initialize, check, generate, migrate, push, pull, status, seed, studio, and drop your database schema with ease. 🐘✨

## Requirements

- **Bun ≥ 1.3** (uses `Bun.SQL` which is built-in)
- **Postgres ≥ 16**
- Built to work alongside `@bungres/orm`.

## Installation

```bash
bun add -d @bungres/kit
```

## Configuration

Create a `bungres.config.ts` file at the root of your project:

```ts
import { defineConfig } from "@bungres/kit";

export default defineConfig({
  schema: "./src/db/schema.ts",
  out: "./bungres", // Directory for migrations & generated files
  dbCredentials: {
    url: Bun.env.DATABASE_URL!,
  },
});
```

## Commands Overview

Run the CLI using Bun:

```bash
bun run bungres --help
```

| Command            | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| `bungres init`     | Initialize bungres project with config file and db folder structure                |
| `bungres check`    | Check for ungenerated schema changes or pending DB migrations (CI drift tool)      |
| `bungres generate` | Write a single timestamped `.sql` migration file with UP/DOWN sections             |
| `bungres migrate`  | Run pending `.sql` UP sections, track applied in `__bungres_migrations`            |
| `bungres rollback` | Automatically revert the last applied migration using its DOWN section             |
| `bungres push`     | Apply schema directly to DB — no files (great for dev/prototyping)                 |
| `bungres pull`     | Introspect the DB and generate TypeScript schema                                   |
| `bungres status`   | Show applied vs pending migrations                                                 |
| `bungres fresh`    | Drop all tables and re-run all migrations from scratch                             |
| `bungres refresh`  | Truncate all tables to quickly reset data without dropping schema                  |
| `bungres seed`     | Execute the seed script, or run the Auto-Seeder using built-in mock fallback       |
| `bungres studio`   | Start a local web interface to browse database data                                |
| `bungres tusky`    | Boot up an interactive REPL connected to the database with schema loaded           |
| `bungres drop`     | Drop all tables, enums, and views defined in the schema (prompts for confirmation) |

### Command Line Flags

- `-c, --config <path>`: Path to custom config file (default: `bungres.config.ts`)
- `-v, --verbose`: Enable verbose SQL statement logging
- `-y, --yes`: Bypass confirmation prompts (non-interactive mode / CI)
- `-f, --force`: Bypass confirmation prompts for `drop` / `push`
- `-h, --help`: Display CLI help text

### Usage Examples

```bash
bun run bungres init
bun run bungres check          # Check schema drift in CI pipeline (exit 0 clean, 1 if drift)
bun run bungres generate -y    # Generate migration without interactive prompts
bun run bungres migrate
bun run bungres rollback
bun run bungres push -y        # Apply schema directly to DB in dev
bun run bungres pull
bun run bungres status
bun run bungres fresh
bun run bungres refresh
bun run bungres seed
bun run bungres studio
bun run bungres tusky
bun run bungres drop -f        # Skip confirmation
```

## Programmatic API

Use `@bungres/kit` in code without the CLI:

```ts
import { loadConfig, loadSchemas, diffSchemas, runMigrate, runCheck } from "@bungres/kit";

const config = await loadConfig();
const isClean = await runCheck(config);

if (!isClean) {
  console.log("Schema changes needed!");
}
```

## Features ✨

- **CI/CD Drift Detection**: `bungres check` detects schema drift or pending DB migrations to keep your builds safe.
- **Non-Interactive Execution**: Use `-y` / `--yes` flags or run in CI environments without prompt blocking.
- **Interactive Terminal UI**: Interactive prompts and spinners powered by `@clack/prompts`.
- **Drizzle-Style Diffs**: Before applying or generating migrations, visually inspect exactly what tables, columns, and enums will be added, dropped, or altered.
- **Enum Alterations**: Native support for enum value expansions via `ALTER TYPE ... ADD VALUE IF NOT EXISTS`.
- **Rollbacks**: Single file migrations with `-- ==== UP ====` and `-- ==== DOWN ====` sections allow you to rollback your schema effortlessly.
- **Advanced Types & Views**: Full native Postgres support for `pgEnum`, Arrays, `pgView`, and `pgMaterializedView`. The differ natively tracks view signature changes and emits safe `DROP` / `CREATE` generation.
- **Intelligent Casting**: Alters column data types seamlessly by automatically managing and restoring `DEFAULT` constraints across incompatible type casts.
- **Auto-Seeder**: Run `bungres seed` without a custom script to automatically generate mock data for your database with auto FK resolution.

## Security Considerations

### ⚠️ REPL Tool (tusky) Security Warning

The `bungres tusky` command provides an interactive REPL (Read-Eval-Print Loop) for development and debugging purposes. Since `@bungres/kit` is installed as a dev dependency, this tool is intended for development use only.

**Security Risks:**
- Uses `eval()` to execute arbitrary JavaScript/TypeScript code
- Has direct access to your database connection
- Can execute any SQL query through the database connection
- Runs with the same permissions as your database user

**Safe Usage Guidelines:**
- Only run `tusky` in local development environments
- Never expose the REPL to external networks or public access
- Use database users with limited permissions for development
- Avoid running in production or staging environments

## License

MIT