@13w/miri 1.1.23 → 1.1.25

package/Readme.md

@@ -1,53 +1,288 @@
-#### Migration manager
-### Migrations folder structure
-
-* migrations/
-  * init/
-    * 01-create-collections.js
-      ```javascript
-      db.createCollection('users');
-      db.createCollection('goods');
-      ```
-    * 02-create-default-users.js
-    ```javascript
-    db.users.insertOne({firstName: 'foo', lastName: 'zoo'});
-    db.users.insertOne({firstName: 'baz', lastName: 'poo'});
-    ```
-    * 03-create-default-goods.js
-    ```javascript
-    db.goods.insertOne({name: 'lemon'});
-    db.goods.insertOne({name: 'orange'});
-    ```
-  * indexes/
-    * users.json
-    ```json
-    [
-      {name: 1}
-    ]
-    ```
-    * goods.json
-    ```json
-    [
-      [{name: 1}, { unique: true }]
-    ]
-    ```
-  * version-1/
-    * 01-02-2023-add-full-name.js
-    ```javascript
-    export const test = () => db.users.countDocuments({ fullName: { $exists: false } });
-    export const up = () => db.users.updateMany({ fullName: { $exists: false } }, [{ $set: { fullName: { $concat: ['$firstName', ' ', '$lastName'] } } }])
-    export const down = () => db.users.updateMany({}, {$unset: { fullName: 1 }})
-    ```
-    * 04-05-2023-add-user-age.js
-    ```javascript
-    export const test = () => db.users.countDocuments({ age: { $exists: false } });
-    export const up => () => db.users.updateMany({ age: { $exists: false } }, {$set: { age: 135 }})
-    export const down = () => db.users.updateMany({}, {$unset: { age: 1 }})
-    ```
-  * version-2/
-    * 05-08-2023-add-price-to-goods.js
-    ```javascript
-    export const test = () => db.goods.countDocuments({ price: { $exists: false } });
-    export const up => () => db.goods.updateMany({ price: { $exists: false } }, { $set: {price: 12.24} })
-    export const down = () => db.goods.updateMany({}, {$unset: { price: 1 }})
-    ```
+# Miri
+
+A MongoDB migration and patch manager with SSH tunneling support. Manages database schema changes through versioned migration scripts, initial setup scripts, and index definitions.
+
+Published as `@13w/miri` on npm.
+
+## Requirements
+
+- Node.js >= 18
+
+## Installation
+
+```bash
+npm install -g @13w/miri
+```
+
+## Quick Start
+
+1. Create a `.mirirc` file in your project root (see [Configuration](#configuration))
+2. Create a `migrations/` directory with your migration scripts (see [Migration Structure](#migration-structure))
+3. Run `miri status` to see pending migrations
+4. Run `miri sync` to apply all pending migrations
+
+## Configuration
+
+Miri reads a `.mirirc` JSON file from the current working directory. All settings can also be overridden via CLI flags.
+
+### Minimal `.mirirc`
+
+```json
+{
+  "db": "mongodb://127.0.0.1:27017/MyDatabase",
+  "migrations": "migrations"
+}
+```
+
+### Full `.mirirc` with environments
+
+```json
+{
+  "db": "mongodb://127.0.0.1:27017/MyDatabase",
+  "migrations": "migrations",
+  "sshUser": "ubuntu",
+
+  "environments": {
+    "dev": {
+      "sshProfile": "my-dev-bastion"
+    },
+    "staging": {
+      "sshProfile": "my-staging-bastion"
+    },
+    "production": {
+      "sshHost": "bastion.example.com",
+      "sshUser": "deploy",
+      "sshKey": "~/.ssh/prod_key"
+    }
+  }
+}
+```
+
+### Configuration Options
+
+| Key | CLI Flag | Default | Description |
+|-----|----------|---------|-------------|
+| `db` | `-d, --db <uri>` | `mongodb://localhost:27017/test` | MongoDB connection URI. The hostname and port are used as the SSH tunnel destination when tunneling is active. |
+| `migrations` | `-m, --migrations <folder>` | `./migrations` | Path to the migrations directory, relative to the working directory. |
+| `directConnection` | `--no-direct-connection` | `true` | Appends `directConnection=true` to the MongoDB URI. Disable this when connecting to a replica set where you want the driver to discover other members. |
+| `sshProfile` | `--ssh-profile <profile>` | — | Name of an SSH host entry in `~/.ssh/config`. When set, miri reads `Hostname`, `Port`, `User`, and `IdentityFile` from the matching SSH config block. Individual SSH fields from CLI flags take precedence over what the profile provides. |
+| `sshHost` | `--ssh-host <host>` | — | SSH bastion/jump host address. Setting this (or `sshProfile`) activates SSH tunneling. |
+| `sshPort` | `--ssh-port <port>` | `22` | SSH port on the bastion host. |
+| `sshUser` | `--ssh-user <user>` | — | SSH username. Can be set at the top level of `.mirirc` as a default for all environments. |
+| `sshKey` | `--ssh-key <path>` | — | Path to the SSH private key. Supports `~/` expansion. If a `.pub` file is given, miri will look for the corresponding private key. |
+| `sshAskPass` | — | `false` | When `true` and the private key is encrypted, miri prompts for the passphrase interactively. |
+
+### Environment Selection
+
+Use `-e <name>` to select a named environment:
+
+```bash
+miri -e dev status       # Uses the "dev" environment
+miri -e production sync  # Uses the "production" environment
+```
+
+**Resolution order** (last wins):
+
+1. Top-level `.mirirc` fields (`db`, `migrations`, `sshUser`, etc.)
+2. Fields from the selected `environments.<name>` block
+3. CLI flags
+
+If no `-e` flag is provided, miri looks for an environment named `"default"`. If that doesn't exist, the top-level settings are used directly.
+
+### SSH Tunneling
+
+When an SSH host is configured (via `sshProfile` or `sshHost`), miri creates a local SSH tunnel to the MongoDB host before connecting. The tunnel forwards a random local port to the `hostname:port` extracted from the `db` URI.
+
+**Authentication priority:**
+
+1. **SSH Agent** — If `SSH_AUTH_SOCK` is set and the key is loaded in the agent, the agent is used automatically.
+2. **Private key file** — If a key file is configured and not already in the agent, it is read from disk.
+3. **Passphrase prompt** — If the private key is encrypted (passphrase-protected), miri prompts for the passphrase on stdin.
+
+## CLI Reference
+
+```
+miri [options] [command]
+```
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `-V, --version` | Output the version number |
+| `-e, --env <environment>` | Environment name from `.mirirc` (default: `"default"`) |
+| `-m, --migrations <folder>` | Folder with migrations |
+| `-d, --db <mongo-uri>` | MongoDB connection URI |
+| `--no-direct-connection` | Disable `directConnection` on the MongoDB URI |
+| `--ssh-profile <profile>` | Connect via SSH using an `~/.ssh/config` profile |
+| `--ssh-host <host>` | SSH proxy host |
+| `--ssh-port <port>` | SSH proxy port |
+| `--ssh-user <user>` | SSH proxy user |
+| `--ssh-key <path>` | SSH proxy identity key |
+
+### Commands
+
+#### `miri status [--all]`
+
+Displays the status of all versioned patches. Use `--all` to include init patches.
+
+Statuses:
+- **Ok** — Applied and unchanged
+- **New** — Exists locally but not yet applied
+- **Updated** — Applied, but `test` or `down` functions have changed (safe to re-sync)
+- **Changed** — Applied, but the `up` function has changed (requires revert + reapply)
+- **Degraded** — Applied, but `test()` returns > 0 (the migration's postcondition is no longer met)
+- **Removed** — In the database but no longer exists locally
+
+#### `miri sync [--degraded] [--all]`
+
+Applies all pending migrations in order: init scripts, then indexes, then versioned patches.
+
+- `--degraded` — Also re-apply patches whose status is Degraded
+- `--all` — Re-apply all patches regardless of status
+
+#### `miri init apply [patch] [--no-exec] [--force]`
+
+Runs init scripts from `migrations/init/`. Optionally target a single patch by name.
+
+- `--no-exec` — Mark the patch as applied without executing it
+- `--force` — Re-apply even if already recorded as done
+
+#### `miri init remove <patch> [--no-exec]`
+
+Removes an init patch record from the database.
+
+- `--no-exec` — Remove the record without executing the script
+
+#### `miri init status`
+
+Displays the status of init patches only.
+
+#### `miri indexes status [collection] [-q, --quiet]`
+
+Shows the diff between local index definitions and the indexes currently in MongoDB.
+
+- `--quiet` — Only show changes (hide indexes that are already applied)
+
+#### `miri indexes sync [collection]`
+
+Creates new indexes and drops removed indexes. Optionally target a single collection.
+
+#### `miri patch diff`
+
+Displays the diff between local versioned patches and what's applied in the database.
+
+#### `miri patch sync [--remote] [--degraded] [--all]`
+
+Apply versioned patches.
+
+- `--remote` — Remote only
+- `--degraded` — Re-apply degraded patches
+- `--all` — Re-apply all patches
+
+#### `miri patch apply <group> <patch> [--no-exec]`
+
+Apply a single specific patch by group and name.
+
+#### `miri patch remove <group> <patch> [--no-exec]`
+
+Revert and remove a single patch. Runs the `down()` function then deletes the record.
+
+## Migration Structure
+
+```
+migrations/
+├── init/                          # One-time setup scripts
+│   ├── 01-create-collections.js
+│   └── 02-seed-data.js
+├── indexes/                       # Index definitions (JSON)
+│   ├── users.json
+│   └── goods.json
+├── version-1/                     # Versioned patch group
+│   ├── 01-02-2023-add-full-name.js
+│   └── 04-05-2023-add-user-age.js
+└── version-2/                     # Another patch group
+    └── 05-08-2023-add-price.js
+```
+
+### Init Scripts
+
+Simple scripts executed in a `mongosh` context. They run once and are tracked by name.
+
+```javascript
+db.createCollection('users');
+db.createCollection('goods');
+```
+
+### Versioned Patches
+
+Each patch must export three functions:
+
+```javascript
+// test: returns the count of documents that still need migrating
+// When this returns 0, the migration is considered fully applied
+export const test = () =>
+  db.users.countDocuments({ fullName: { $exists: false } });
+
+// up: applies the migration
+export const up = () =>
+  db.users.updateMany(
+    { fullName: { $exists: false } },
+    [{ $set: { fullName: { $concat: ['$firstName', ' ', '$lastName'] } } }]
+  );
+
+// down: reverts the migration
+export const down = () =>
+  db.users.updateMany({}, { $unset: { fullName: 1 } });
+```
+
+**Execution flow during sync:**
+1. `test()` is called to check if migration is needed
+2. If the patch was previously applied but has changed, `down()` is called first to revert
+3. `up()` is called to apply the migration
+4. The patch content (hashes of test/up/down) is stored in the `migrations` collection
+
+### Index Definitions
+
+JSON files in `migrations/indexes/`, named after the target collection. Each file contains an array of index specifications:
+
+```json
+[
+  { "name": 1 },
+  [{ "email": 1 }, { "unique": true }]
+]
+```
+
+- A plain object defines the index key (e.g., `{ "name": 1 }`)
+- An array of `[keySpec, options]` lets you pass index options like `unique`, `sparse`, etc.
+
+### Environment Variables
+
+Migration scripts can access environment variables prefixed with `MIRI_`. Inside scripts, they're available on the `__env` object with the prefix stripped:
+
+```bash
+MIRI_ADMIN_EMAIL=admin@example.com miri sync
+```
+
+```javascript
+// In a migration script:
+export const up = () =>
+  db.users.updateOne(
+    { role: 'admin' },
+    { $set: { email: __env.ADMIN_EMAIL } }
+  );
+```
+
+## How Miri Tracks State
+
+Miri stores migration state in a `migrations` collection in the target database. Each applied patch is recorded with:
+
+- `group` — The subdirectory name (e.g., `version-1`, `init`)
+- `name` — The filename
+- `content` — SHA-256 hashes and base64-encoded bodies of `test`, `up`, and `down` functions
+
+This allows miri to detect when a migration script has been modified since it was last applied and report the appropriate status (Updated, Changed).
+
+## License
+
+MIT

package/Readme.orig.md

@@ -0,0 +1,54 @@
+#### Migration manager
+### Migrations folder structure
+
+* migrations/
+  * init/
+    * 01-create-collections.js
+      ```javascript
+      db.createCollection('users');
+      db.createCollection('goods');
+      ```
+    * 02-create-default-users.js
+    ```javascript
+    db.users.insertOne({firstName: 'foo', lastName: 'zoo'});
+    db.users.insertOne({firstName: 'baz', lastName: 'poo'});
+    ```
+    * 03-create-default-goods.js
+    ```javascript
+    db.goods.insertOne({name: 'lemon'});
+    db.goods.insertOne({name: 'orange'});
+    ```
+  * indexes/
+    * users.json
+    ```json
+    [
+      {name: 1}
+    ]
+    ```
+    * goods.json
+    ```json
+    [
+      [{name: 1}, { unique: true }]
+    ]
+    ```
+  * version-1/
+    * 01-02-2023-add-full-name.js
+    ```javascript
+    export const test = () => db.users.countDocuments({ fullName: { $exists: false } });
+    export const up = () => db.users.updateMany({ fullName: { $exists: false } }, [{ $set: { fullName: { $concat: ['$firstName', ' ', '$lastName'] } } }])
+    export const down = () => db.users.updateMany({}, {$unset: { fullName: 1 }})
+    ```
+    * 04-05-2023-add-user-age.js
+    ```javascript
+    export const test = () => db.users.countDocuments({ age: { $exists: false } });
+    export const up => () => db.users.updateMany({ age: { $exists: false } }, {$set: { age: 135 }})
+    export const down = () => db.users.updateMany({}, {$unset: { age: 1 }})
+    ```
+  * version-2/
+    * 05-08-2023-add-price-to-goods.js
+    ```javascript
+    export const test = () => db.goods.countDocuments({ price: { $exists: false } });
+    export const up => () => db.goods.updateMany({ price: { $exists: false } }, { $set: {price: 12.24} })
+    export const down = () => db.goods.updateMany({}, {$unset: { price: 1 }})
+    ```
+

package/dist/evaluator.js

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'node:events';
 import { inspect } from 'node:util';
 import { createContext, runInContext, SourceTextModule, SyntheticModule } from 'node:vm';
-import { CliServiceProvider } from '@mongosh/service-provider-server';
+import { NodeDriverServiceProvider } from '@mongosh/service-provider-node-driver';
 import { ShellInstanceState } from '@mongosh/shell-api';
 import { ShellEvaluator } from '@mongosh/shell-evaluator';
 import colors from 'colors';
@@ -27,7 +27,7 @@ export async function evaluateMongo(client, code, filename = '[no file]') {
     const context = createContext({ __env });
     const bus = new EventEmitter();
     // console.log(`Client status! ${(<{ topology: { isConnected: () => boolean } } & MongoClient>client)?.topology?.isConnected() ? '' : 'not'} connected`)
-    const cliServiceProvider = new CliServiceProvider(client, bus, {
+    const cliServiceProvider = new NodeDriverServiceProvider(client, bus, {
         productName: 'MIRI: Migration manager',
         productDocsLink: 'https://example.com/',
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@13w/miri",
   "description": "MongoDB patch manager",
-  "version": "1.1.23",
+  "version": "1.1.25",
   "type": "module",
   "engines": {
     "node": ">=18"
@@ -25,21 +25,21 @@
   "main": "bin/miri",
   "types": "types/miri.d.ts",
   "dependencies": {
-    "@mongosh/service-provider-server": "^2.3.2",
-    "@mongosh/shell-api": "^3.29.1",
-    "@mongosh/shell-evaluator": "^3.29.1",
+    "@mongosh/service-provider-node-driver": "^5.0.11",
+    "@mongosh/shell-api": "^5.1.9",
+    "@mongosh/shell-evaluator": "^5.1.9",
     "colors": "^1.4.0",
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "console-table-printer": "^2.15.0",
-    "mongodb": "^6.21.0",
-    "ssh-config": "^5.0.4",
+    "mongodb": "^7.2.0",
+    "ssh-config": "^5.1.0",
     "tunnel-ssh": "^5.2.0"
   },
   "devDependencies": {
-    "@types/node": "^25.1.0",
-    "mongodb-log-writer": "^2.5.5",
+    "@types/node": "^25.6.0",
+    "mongodb-log-writer": "^2.5.12",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "license": "MIT",
   "scripts": {