@noego/proper 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/proper",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "",
   "main": "bin/index.js",
   "module": "bin/index.mjs",
@@ -64,6 +64,7 @@
     "source-map-support": "^0.5.21",
     "sqlite": "^5.1.1",
     "sqlite3": "^5.1.7",
-    "tsx": "^4.19.4"
+    "tsx": "^4.19.4",
+    "yaml": "^2.9.0"
   }
 }

package/readme.md

@@ -266,6 +266,103 @@ describe('Database Tests', () => {
 
 ---
 
+## Ledger Patches (`proper patch`)
+
+Ledger patches are one-shot, versioned YAML files that repair `proper_migrations`
+history **without executing schema SQL**. Use them when applied migration files
+were renamed after installation, when a ledger row is missing for schema that
+already exists, or when a ledger row wrongly claims success.
+
+Patches are discovered and applied automatically before Proper reads migration
+completion state (CLI and `MigrationRunnerFactory.create()` alike), are
+transactional, are applied at most once per configured migration ledger, and
+work identically for MySQL/MariaDB, SQLite, and PostgreSQL.
+
+### Creating a patch
+
+```bash
+proper patch fix_renamed_keys
+proper patch --name fix_renamed_keys
+```
+
+This scaffolds `<patch_folder>/<timestamp>_fix_renamed_keys.yaml` without
+opening a database. The scaffold's `operations: []` is intentionally not
+runnable — complete the file before running another database-backed command.
+
+### Configuration
+
+```jsonc
+{
+  "patch_folder": "patches",       // default: a `patches` sibling of migration_folder
+  "patch_table": "proper_patches"  // default
+}
+```
+
+Patches may also be co-located with migrations by setting `patch_folder` to
+the same path as `migration_folder` — migration discovery only considers
+`*.up/down.sql|js` files and patch discovery only considers top-level
+`*.yaml` files, so the two never interfere.
+
+### Patch file format (version 1)
+
+```yaml
+version: 1
+description: fix hand-stamped migration names
+operations:
+  - rename_migration:
+      from: 1787905000000_create_conversation_run_lifecycle
+      to: 1787941600000_create_conversation_run_lifecycle
+  - mark_applied:
+      key: 1787941700000_existing_schema_baseline
+  - unmark_applied:
+      key: 1787941800000_incorrect_ledger_row
+```
+
+Operations run in file order, then operation order. Each is a conditional
+bookkeeping repair:
+
+- `rename_migration` — moves a ledger row from `from` to `to`; a no-op when the
+  database already converged; a hard conflict when both keys exist.
+- `mark_applied` — inserts a ledger row without running `up` SQL (you are
+  responsible for verifying the schema already matches).
+- `unmark_applied` — deletes a ledger row without running `down` SQL, making
+  the migration pending again.
+
+Parsing is strict: unknown fields/verbs, duplicate keys, YAML anchors/aliases,
+merge keys, and custom tags are rejected. There is no raw SQL escape hatch.
+
+### Immutability
+
+**Patch files are permanent, append-only migration history.** Once any database
+records a patch, the file must never be edited, renamed, or deleted — Proper
+stores a SHA-256 checksum at application time and refuses to run migrations if
+an applied patch's file is missing or changed. A correction is a new, later
+patch (`A -> B -> C` and `A -> B -> A` chains are supported and validated
+against the current migration files).
+
+### Deployment and rollback warning
+
+A history rename must ship the renamed migration files, the patch file(s), and
+a patch-aware Proper version **in the same application artifact**. Do not run
+old and new application versions' migration startup concurrently during the
+first deployment of a rename. After a rename patch commits, rolling back to an
+artifact that only contains the old migration filenames is unsafe — that old
+runner can attempt the old migration again. Roll back only to artifacts
+consistent with the repaired ledger, or restore the database separately.
+
+`proper down` and `proper reset` never touch patch history; destructive
+`terminate()` drops both the migration table and the patch table.
+
+### Programmatic API
+
+```ts
+const runner = await MigrationRunnerFactory.create("proper.json"); // patches already applied
+const results: PatchApplyResult[] = await runner.applyPendingPatches(); // idempotent
+const path: string = runner.createPatch("fix_renamed_keys"); // scaffold, no DB
+```
+
+---
+
 ## Seeding
 
 SQL Proper supports a powerful seeding feature that allows you to populate your database with initial data (reference data, test users, etc.). Seeds can be SQL files or JavaScript/TypeScript modules.