@dads-framework/authorization-migration 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +90 -17
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,17 +1,90 @@
1
- # @dads-framework/authorization-migration — the authorization schema journal
2
-
3
- Moves a SpiceDB schema forward the way the database migrator moves Postgres:
4
- an ordered journal of `NNNN_slug` entries, each holding the full `schema.zed`
5
- snapshot it writes and the relationship steps that keep access intact (backfill
6
- or move first, then delete). The runner refuses gaps, duplicates, folders
7
- missing from the journal, and a snapshot that drops the journal's own
8
- definition. Applied entries are recorded as `authz/migration_version`
9
- relationships, so a rerun is a no-op.
10
-
11
- Authorization changes (`authz-changes/`) are the patch form: each records the
12
- definitions it changes and what it depends on, so two branches can add changes
13
- without renumbering a shared index. `scaffoldMigration` and
14
- `scaffoldAuthorizationChange` author new entries; `renumberMigration` moves an
15
- entry that collided with another branch.
16
-
17
- The journal folder is the caller's: nothing here assumes where it lives.
1
+ # `@dads-framework/authorization-migration`
2
+
3
+ Scaffold and apply ordered SpiceDB schema snapshots and relationship migration steps.
4
+
5
+ ## Try it
6
+
7
+ The generated starter uses Postgres for authorization in
8
+ [`assembly/services.ts`](../../../apps/kit-workbench/assembly/services.ts). For the SpiceDB schema journal, see the repository's
9
+ [journal runner tests](./src/lib/run-authorization-migrations.test.ts), which
10
+ show ordered application and a rerun that skips applied entries.
11
+
12
+ Use Node.js 22 or later. The script creates a temporary journal, previews the
13
+ first migration ID, then checks that scaffolding the same schema again is a
14
+ no-op. No SpiceDB instance is needed to scaffold.
15
+
16
+ ```sh
17
+ npm install @dads-framework/authorization-migration
18
+ npm install -D tsx
19
+ ```
20
+
21
+ Save as `scaffold-journal.mts` and run `npx tsx scaffold-journal.mts`.
22
+
23
+ <!-- dads:check-example -->
24
+
25
+ ```ts
26
+ import { mkdtemp, rm } from "node:fs/promises";
27
+ import { tmpdir } from "node:os";
28
+ import { join } from "node:path";
29
+ import {
30
+ listShippedAuthorizationMigrationIds,
31
+ scaffoldMigration,
32
+ } from "@dads-framework/authorization-migration";
33
+
34
+ const journalFolder = await mkdtemp(join(tmpdir(), "dads-journal-"));
35
+ try {
36
+ const input = {
37
+ journalFolder,
38
+ mode: "new",
39
+ slug: "baseline",
40
+ composedSchema: `
41
+ definition authz/migration_version {}
42
+ definition authz/migration_journal {
43
+ relation applied: authz/migration_version
44
+ }
45
+ definition user {}
46
+ `,
47
+ } satisfies Parameters<typeof scaffoldMigration>[0];
48
+
49
+ console.log((await scaffoldMigration(input)).action);
50
+ console.log(
51
+ (await listShippedAuthorizationMigrationIds(journalFolder)).join(),
52
+ );
53
+ console.log((await scaffoldMigration(input)).action);
54
+ } finally {
55
+ await rm(journalFolder, { recursive: true, force: true });
56
+ }
57
+ ```
58
+
59
+ The script prints `created`, `0001_baseline`, and `up-to-date`. To retain
60
+ the generated `index.ts`, `schema.zed`, and `migration.ts` in your app, use
61
+ an existing journal directory and omit the temporary directory cleanup.
62
+
63
+ ## Use it
64
+
65
+ Pass the generated index's `journal`, the absolute path of its directory, an
66
+ `AuthorizationMigrationStore`, and a logger with an `info` method to
67
+ `runAuthorizationMigrations`. For a development run against SpiceDB, start
68
+ with a dedicated datastore and construct `SpiceDbAuthorization` from
69
+ `@dads-framework/authorization` with its endpoint and credentials. Pass the
70
+ adapter as `store`. A successful run logs the applied ID. Rerunning the
71
+ same journal reports zero newly applied entries.
72
+
73
+ For independently authored patches, use `scaffoldAuthorizationChange` and
74
+ pass their directory as `changesFolder` on the same runner. Each patch
75
+ records the definitions it changes and the changes it depends on.
76
+ `renumberMigration` moves a snapshot entry that collided with another branch.
77
+
78
+ ## What it refuses to do
79
+
80
+ The runner rejects gaps, duplicate entries, unregistered folders, and snapshots
81
+ that drop the journal definition. A destructive entry after the baseline
82
+ requires the relationship steps that make its schema write legal.
83
+
84
+ ## Contract
85
+
86
+ Each `NNNN_slug` holds a full schema snapshot. The runner calls
87
+ `beforeSchemaWrite`, writes the snapshot, and then calls `afterSchemaWrite`
88
+ when those steps are present. It records success as an
89
+ `authz/migration_version` relationship. A failure leaves the marker
90
+ unwritten. Make relationship steps safe to repeat when retrying an entry.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dads-framework/authorization-migration",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=22"
@@ -16,7 +16,7 @@
16
16
  "README.md"
17
17
  ],
18
18
  "dependencies": {
19
- "@dads-framework/access": "0.1.0",
19
+ "@dads-framework/access": "0.2.0",
20
20
  "jiti": "2.4.2",
21
21
  "zod": "^4.4.3"
22
22
  },