@prisma-next/migration-tools 0.5.0-dev.8 → 0.5.0-dev.81
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.
- package/README.md +34 -22
- package/dist/{constants-BRi0X7B_.mjs → constants-DWV9_o2Z.mjs} +2 -2
- package/dist/{constants-BRi0X7B_.mjs.map → constants-DWV9_o2Z.mjs.map} +1 -1
- package/dist/errors-EPL_9p9f.mjs +297 -0
- package/dist/errors-EPL_9p9f.mjs.map +1 -0
- package/dist/exports/aggregate.d.mts +614 -0
- package/dist/exports/aggregate.d.mts.map +1 -0
- package/dist/exports/aggregate.mjs +611 -0
- package/dist/exports/aggregate.mjs.map +1 -0
- package/dist/exports/constants.d.mts.map +1 -1
- package/dist/exports/constants.mjs +2 -3
- package/dist/exports/errors.d.mts +68 -0
- package/dist/exports/errors.d.mts.map +1 -0
- package/dist/exports/errors.mjs +2 -0
- package/dist/exports/graph.d.mts +2 -0
- package/dist/exports/graph.mjs +1 -0
- package/dist/exports/hash.d.mts +52 -0
- package/dist/exports/hash.d.mts.map +1 -0
- package/dist/exports/hash.mjs +2 -0
- package/dist/exports/invariants.d.mts +34 -0
- package/dist/exports/invariants.d.mts.map +1 -0
- package/dist/exports/invariants.mjs +2 -0
- package/dist/exports/io.d.mts +66 -6
- package/dist/exports/io.d.mts.map +1 -1
- package/dist/exports/io.mjs +2 -3
- package/dist/exports/metadata.d.mts +2 -0
- package/dist/exports/metadata.mjs +1 -0
- package/dist/exports/migration-graph.d.mts +2 -0
- package/dist/exports/migration-graph.mjs +2 -0
- package/dist/exports/migration-ts.d.mts.map +1 -1
- package/dist/exports/migration-ts.mjs +2 -4
- package/dist/exports/migration-ts.mjs.map +1 -1
- package/dist/exports/migration.d.mts +15 -14
- package/dist/exports/migration.d.mts.map +1 -1
- package/dist/exports/migration.mjs +70 -43
- package/dist/exports/migration.mjs.map +1 -1
- package/dist/exports/package.d.mts +3 -0
- package/dist/exports/package.mjs +1 -0
- package/dist/exports/refs.d.mts.map +1 -1
- package/dist/exports/refs.mjs +3 -4
- package/dist/exports/refs.mjs.map +1 -1
- package/dist/exports/spaces.d.mts +550 -0
- package/dist/exports/spaces.d.mts.map +1 -0
- package/dist/exports/spaces.mjs +223 -0
- package/dist/exports/spaces.mjs.map +1 -0
- package/dist/graph-HMWAldoR.d.mts +28 -0
- package/dist/graph-HMWAldoR.d.mts.map +1 -0
- package/dist/hash-By50zM_E.mjs +74 -0
- package/dist/hash-By50zM_E.mjs.map +1 -0
- package/dist/invariants-Duc8f9NM.mjs +52 -0
- package/dist/invariants-Duc8f9NM.mjs.map +1 -0
- package/dist/io-D13dLvUh.mjs +239 -0
- package/dist/io-D13dLvUh.mjs.map +1 -0
- package/dist/metadata-CFvm3ayn.d.mts +2 -0
- package/dist/migration-graph-DGNnKDY5.mjs +523 -0
- package/dist/migration-graph-DGNnKDY5.mjs.map +1 -0
- package/dist/migration-graph-DulOITvG.d.mts +124 -0
- package/dist/migration-graph-DulOITvG.d.mts.map +1 -0
- package/dist/op-schema-D5qkXfEf.mjs +13 -0
- package/dist/op-schema-D5qkXfEf.mjs.map +1 -0
- package/dist/package-BjiZ7KDy.d.mts +21 -0
- package/dist/package-BjiZ7KDy.d.mts.map +1 -0
- package/dist/read-contract-space-contract-C3-1eyaI.mjs +298 -0
- package/dist/read-contract-space-contract-C3-1eyaI.mjs.map +1 -0
- package/package.json +42 -17
- package/src/aggregate/loader.ts +409 -0
- package/src/aggregate/marker-types.ts +16 -0
- package/src/aggregate/planner-types.ts +171 -0
- package/src/aggregate/planner.ts +158 -0
- package/src/aggregate/project-schema-to-space.ts +64 -0
- package/src/aggregate/strategies/graph-walk.ts +118 -0
- package/src/aggregate/strategies/synth.ts +122 -0
- package/src/aggregate/types.ts +89 -0
- package/src/aggregate/verifier.ts +230 -0
- package/src/assert-descriptor-self-consistency.ts +70 -0
- package/src/compute-extension-space-apply-path.ts +152 -0
- package/src/concatenate-space-apply-inputs.ts +90 -0
- package/src/detect-space-contract-drift.ts +91 -0
- package/src/emit-contract-space-artefacts.ts +70 -0
- package/src/errors.ts +251 -17
- package/src/exports/aggregate.ts +42 -0
- package/src/exports/errors.ts +8 -0
- package/src/exports/graph.ts +1 -0
- package/src/exports/hash.ts +2 -0
- package/src/exports/invariants.ts +1 -0
- package/src/exports/io.ts +3 -1
- package/src/exports/metadata.ts +1 -0
- package/src/exports/{dag.ts → migration-graph.ts} +3 -2
- package/src/exports/migration.ts +0 -1
- package/src/exports/package.ts +2 -0
- package/src/exports/spaces.ts +49 -0
- package/src/gather-disk-contract-space-state.ts +62 -0
- package/src/graph-ops.ts +57 -30
- package/src/graph.ts +25 -0
- package/src/hash.ts +91 -0
- package/src/invariants.ts +56 -0
- package/src/io.ts +163 -40
- package/src/metadata.ts +1 -0
- package/src/migration-base.ts +97 -56
- package/src/migration-graph.ts +676 -0
- package/src/op-schema.ts +11 -0
- package/src/package.ts +21 -0
- package/src/plan-all-spaces.ts +76 -0
- package/src/read-contract-space-contract.ts +44 -0
- package/src/read-contract-space-head-ref.ts +63 -0
- package/src/space-layout.ts +48 -0
- package/src/verify-contract-spaces.ts +272 -0
- package/dist/attestation-BnzTb0Qp.mjs +0 -65
- package/dist/attestation-BnzTb0Qp.mjs.map +0 -1
- package/dist/errors-BmiSgz1j.mjs +0 -160
- package/dist/errors-BmiSgz1j.mjs.map +0 -1
- package/dist/exports/attestation.d.mts +0 -37
- package/dist/exports/attestation.d.mts.map +0 -1
- package/dist/exports/attestation.mjs +0 -4
- package/dist/exports/dag.d.mts +0 -51
- package/dist/exports/dag.d.mts.map +0 -1
- package/dist/exports/dag.mjs +0 -386
- package/dist/exports/dag.mjs.map +0 -1
- package/dist/exports/types.d.mts +0 -35
- package/dist/exports/types.d.mts.map +0 -1
- package/dist/exports/types.mjs +0 -3
- package/dist/io-Cd6GLyjK.mjs +0 -153
- package/dist/io-Cd6GLyjK.mjs.map +0 -1
- package/dist/types-DyGXcWWp.d.mts +0 -71
- package/dist/types-DyGXcWWp.d.mts.map +0 -1
- package/src/attestation.ts +0 -81
- package/src/dag.ts +0 -426
- package/src/exports/attestation.ts +0 -2
- package/src/exports/types.ts +0 -10
- package/src/types.ts +0 -66
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
import { C as errorProvidedInvariantsMismatch, c as errorInvalidDestName, d as errorInvalidManifest, g as errorInvalidSlug, i as errorDirectoryExists, u as errorInvalidJson, v as errorMigrationHashMismatch, y as errorMissingFile } from "./errors-EPL_9p9f.mjs";
|
|
2
|
+
import { n as verifyMigrationHash, r as canonicalizeJson } from "./hash-By50zM_E.mjs";
|
|
3
|
+
import { t as deriveProvidedInvariants } from "./invariants-Duc8f9NM.mjs";
|
|
4
|
+
import { n as MigrationOpsSchema } from "./op-schema-D5qkXfEf.mjs";
|
|
5
|
+
import { basename, dirname, join, resolve } from "pathe";
|
|
6
|
+
import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
|
|
7
|
+
import { type } from "arktype";
|
|
8
|
+
//#region src/io.ts
|
|
9
|
+
const MANIFEST_FILE = "migration.json";
|
|
10
|
+
const OPS_FILE = "ops.json";
|
|
11
|
+
const MAX_SLUG_LENGTH = 64;
|
|
12
|
+
function hasErrnoCode(error, code) {
|
|
13
|
+
return error instanceof Error && error.code === code;
|
|
14
|
+
}
|
|
15
|
+
const MigrationMetadataSchema = type({
|
|
16
|
+
"+": "reject",
|
|
17
|
+
from: "string > 0 | null",
|
|
18
|
+
to: "string",
|
|
19
|
+
migrationHash: "string",
|
|
20
|
+
fromContract: "object | null",
|
|
21
|
+
toContract: "object",
|
|
22
|
+
hints: type({
|
|
23
|
+
used: "string[]",
|
|
24
|
+
applied: "string[]",
|
|
25
|
+
plannerVersion: "string"
|
|
26
|
+
}),
|
|
27
|
+
labels: "string[]",
|
|
28
|
+
providedInvariants: "string[]",
|
|
29
|
+
"authorship?": type({
|
|
30
|
+
"author?": "string",
|
|
31
|
+
"email?": "string"
|
|
32
|
+
}),
|
|
33
|
+
"signature?": type({
|
|
34
|
+
keyId: "string",
|
|
35
|
+
value: "string"
|
|
36
|
+
}).or("null"),
|
|
37
|
+
createdAt: "string"
|
|
38
|
+
});
|
|
39
|
+
async function writeMigrationPackage(dir, metadata, ops) {
|
|
40
|
+
await mkdir(dirname(dir), { recursive: true });
|
|
41
|
+
try {
|
|
42
|
+
await mkdir(dir);
|
|
43
|
+
} catch (error) {
|
|
44
|
+
if (hasErrnoCode(error, "EEXIST")) throw errorDirectoryExists(dir);
|
|
45
|
+
throw error;
|
|
46
|
+
}
|
|
47
|
+
await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(metadata, null, 2), { flag: "wx" });
|
|
48
|
+
await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: "wx" });
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Materialise an in-memory {@link MigrationPackage} to a per-space
|
|
52
|
+
* directory on disk.
|
|
53
|
+
*
|
|
54
|
+
* Writes three files under `<targetDir>/<pkg.dirName>/`:
|
|
55
|
+
*
|
|
56
|
+
* - `migration.json` — the manifest (pretty-printed, matches
|
|
57
|
+
* {@link writeMigrationPackage}'s output for byte-for-byte parity with
|
|
58
|
+
* app-space migrations).
|
|
59
|
+
* - `ops.json` — the operation list (pretty-printed).
|
|
60
|
+
* - `contract.json` — the canonical-JSON serialisation of
|
|
61
|
+
* `metadata.toContract`. This is the per-package post-state contract
|
|
62
|
+
* snapshot; the canonicalisation pass guarantees byte-determinism so
|
|
63
|
+
* re-emitting the same package across machines / runs produces an
|
|
64
|
+
* identical file.
|
|
65
|
+
*
|
|
66
|
+
* Distinct verb from the lower-level {@link writeMigrationPackage}
|
|
67
|
+
* (which takes constituent `(metadata, ops)`): callers reading
|
|
68
|
+
* `materialise…` know they are persisting a struct-typed package
|
|
69
|
+
* including its contract-snapshot side car.
|
|
70
|
+
*
|
|
71
|
+
* Overwrite-idempotent: the per-package directory is cleared before
|
|
72
|
+
* each emit, so re-running against the same `targetDir` produces
|
|
73
|
+
* byte-identical contents and never leaves stale files behind. The
|
|
74
|
+
* spec's "re-emitting the same package across runs / machines produces
|
|
75
|
+
* byte-identical files" guarantee (§ 3) covers both same-dir and
|
|
76
|
+
* fresh-dir re-emits. The lower-level {@link writeMigrationPackage}
|
|
77
|
+
* stays strict because the CLI authoring path (`migration plan` /
|
|
78
|
+
* `migration new`) deliberately refuses to clobber an existing
|
|
79
|
+
* authored migration; this helper is the re-emit path that is
|
|
80
|
+
* supposed to converge on a single canonical on-disk shape.
|
|
81
|
+
*
|
|
82
|
+
* @see specs/framework-mechanism.spec.md § 3 — Emission helper (T1.7).
|
|
83
|
+
*/
|
|
84
|
+
async function materialiseMigrationPackage(targetDir, pkg) {
|
|
85
|
+
const dir = join(targetDir, pkg.dirName);
|
|
86
|
+
await rm(dir, {
|
|
87
|
+
recursive: true,
|
|
88
|
+
force: true
|
|
89
|
+
});
|
|
90
|
+
await writeMigrationPackage(dir, pkg.metadata, pkg.ops);
|
|
91
|
+
await writeFile(join(dir, "contract.json"), `${canonicalizeJson(pkg.metadata.toContract)}\n`, { flag: "wx" });
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Idempotent variant of {@link materialiseMigrationPackage}: writes the
|
|
95
|
+
* package only if `<targetDir>/<pkg.dirName>/` does not already exist on
|
|
96
|
+
* disk as a directory; returns `{ written: false }` when the package
|
|
97
|
+
* directory is present (no rewrite, no comparison — by-existence skip).
|
|
98
|
+
*
|
|
99
|
+
* Concretely:
|
|
100
|
+
* - existing directory → skip silently, return `{ written: false }`.
|
|
101
|
+
* - missing path → write three files via {@link materialiseMigrationPackage},
|
|
102
|
+
* return `{ written: true }`.
|
|
103
|
+
* - path exists but is not a directory (file/symlink) → treated as
|
|
104
|
+
* missing; {@link materialiseMigrationPackage} will attempt creation
|
|
105
|
+
* and fail with an appropriate OS error.
|
|
106
|
+
* - any other I/O error from `stat` → propagated unchanged.
|
|
107
|
+
*
|
|
108
|
+
* Used by the CLI's `runContractSpaceExtensionMigrationsPass` to
|
|
109
|
+
* materialise extension migration packages into a project's
|
|
110
|
+
* `migrations/<spaceId>/` directory, and by extension-package tests
|
|
111
|
+
* that mirror the same idempotent-rematerialise property locally
|
|
112
|
+
* without taking a CLI dependency.
|
|
113
|
+
*/
|
|
114
|
+
async function materialiseExtensionMigrationPackageIfMissing(targetDir, pkg) {
|
|
115
|
+
if (await directoryExists(join(targetDir, pkg.dirName))) return { written: false };
|
|
116
|
+
await materialiseMigrationPackage(targetDir, pkg);
|
|
117
|
+
return { written: true };
|
|
118
|
+
}
|
|
119
|
+
async function directoryExists(p) {
|
|
120
|
+
try {
|
|
121
|
+
return (await stat(p)).isDirectory();
|
|
122
|
+
} catch (error) {
|
|
123
|
+
if (hasErrnoCode(error, "ENOENT")) return false;
|
|
124
|
+
throw error;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Copy a list of files into `destDir`, optionally renaming each one.
|
|
129
|
+
*
|
|
130
|
+
* The destination directory is created (with `recursive: true`) if it
|
|
131
|
+
* does not already exist. Each source path is copied byte-for-byte into
|
|
132
|
+
* `destDir/<destName>`; missing sources throw `ENOENT`. The helper is
|
|
133
|
+
* intentionally generic: callers own the list of files (e.g. a contract
|
|
134
|
+
* emitter's emitted output) and the naming convention (e.g. renaming
|
|
135
|
+
* the destination contract to `end-contract.*` and the source contract
|
|
136
|
+
* to `start-contract.*`).
|
|
137
|
+
*/
|
|
138
|
+
async function copyFilesWithRename(destDir, files) {
|
|
139
|
+
await mkdir(destDir, { recursive: true });
|
|
140
|
+
for (const file of files) {
|
|
141
|
+
if (basename(file.destName) !== file.destName) throw errorInvalidDestName(file.destName);
|
|
142
|
+
await copyFile(file.sourcePath, join(destDir, file.destName));
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
async function writeMigrationMetadata(dir, metadata) {
|
|
146
|
+
await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\n`);
|
|
147
|
+
}
|
|
148
|
+
async function writeMigrationOps(dir, ops) {
|
|
149
|
+
await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
|
|
150
|
+
}
|
|
151
|
+
async function readMigrationPackage(dir) {
|
|
152
|
+
const absoluteDir = resolve(dir);
|
|
153
|
+
const manifestPath = join(absoluteDir, MANIFEST_FILE);
|
|
154
|
+
const opsPath = join(absoluteDir, OPS_FILE);
|
|
155
|
+
let manifestRaw;
|
|
156
|
+
try {
|
|
157
|
+
manifestRaw = await readFile(manifestPath, "utf-8");
|
|
158
|
+
} catch (error) {
|
|
159
|
+
if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(MANIFEST_FILE, absoluteDir);
|
|
160
|
+
throw error;
|
|
161
|
+
}
|
|
162
|
+
let opsRaw;
|
|
163
|
+
try {
|
|
164
|
+
opsRaw = await readFile(opsPath, "utf-8");
|
|
165
|
+
} catch (error) {
|
|
166
|
+
if (hasErrnoCode(error, "ENOENT")) throw errorMissingFile(OPS_FILE, absoluteDir);
|
|
167
|
+
throw error;
|
|
168
|
+
}
|
|
169
|
+
let metadata;
|
|
170
|
+
try {
|
|
171
|
+
metadata = JSON.parse(manifestRaw);
|
|
172
|
+
} catch (e) {
|
|
173
|
+
throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));
|
|
174
|
+
}
|
|
175
|
+
let ops;
|
|
176
|
+
try {
|
|
177
|
+
ops = JSON.parse(opsRaw);
|
|
178
|
+
} catch (e) {
|
|
179
|
+
throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));
|
|
180
|
+
}
|
|
181
|
+
validateMetadata(metadata, manifestPath);
|
|
182
|
+
validateOps(ops, opsPath);
|
|
183
|
+
const derivedInvariants = deriveProvidedInvariants(ops);
|
|
184
|
+
if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) throw errorProvidedInvariantsMismatch(manifestPath, metadata.providedInvariants, derivedInvariants);
|
|
185
|
+
const pkg = {
|
|
186
|
+
dirName: basename(absoluteDir),
|
|
187
|
+
dirPath: absoluteDir,
|
|
188
|
+
metadata,
|
|
189
|
+
ops
|
|
190
|
+
};
|
|
191
|
+
const verification = verifyMigrationHash(pkg);
|
|
192
|
+
if (!verification.ok) throw errorMigrationHashMismatch(absoluteDir, verification.storedHash, verification.computedHash);
|
|
193
|
+
return pkg;
|
|
194
|
+
}
|
|
195
|
+
function arraysEqual(a, b) {
|
|
196
|
+
if (a.length !== b.length) return false;
|
|
197
|
+
for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
|
|
198
|
+
return true;
|
|
199
|
+
}
|
|
200
|
+
function validateMetadata(metadata, filePath) {
|
|
201
|
+
const result = MigrationMetadataSchema(metadata);
|
|
202
|
+
if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);
|
|
203
|
+
}
|
|
204
|
+
function validateOps(ops, filePath) {
|
|
205
|
+
const result = MigrationOpsSchema(ops);
|
|
206
|
+
if (result instanceof type.errors) throw errorInvalidManifest(filePath, result.summary);
|
|
207
|
+
}
|
|
208
|
+
async function readMigrationsDir(migrationsRoot) {
|
|
209
|
+
let entries;
|
|
210
|
+
try {
|
|
211
|
+
entries = await readdir(migrationsRoot);
|
|
212
|
+
} catch (error) {
|
|
213
|
+
if (hasErrnoCode(error, "ENOENT")) return [];
|
|
214
|
+
throw error;
|
|
215
|
+
}
|
|
216
|
+
const packages = [];
|
|
217
|
+
for (const entry of entries.sort()) {
|
|
218
|
+
const entryPath = join(migrationsRoot, entry);
|
|
219
|
+
if (!(await stat(entryPath)).isDirectory()) continue;
|
|
220
|
+
const manifestPath = join(entryPath, MANIFEST_FILE);
|
|
221
|
+
try {
|
|
222
|
+
await stat(manifestPath);
|
|
223
|
+
} catch {
|
|
224
|
+
continue;
|
|
225
|
+
}
|
|
226
|
+
packages.push(await readMigrationPackage(entryPath));
|
|
227
|
+
}
|
|
228
|
+
return packages;
|
|
229
|
+
}
|
|
230
|
+
function formatMigrationDirName(timestamp, slug) {
|
|
231
|
+
const sanitized = slug.toLowerCase().replace(/[^a-z0-9]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
|
|
232
|
+
if (sanitized.length === 0) throw errorInvalidSlug(slug);
|
|
233
|
+
const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);
|
|
234
|
+
return `${timestamp.getUTCFullYear()}${String(timestamp.getUTCMonth() + 1).padStart(2, "0")}${String(timestamp.getUTCDate()).padStart(2, "0")}T${String(timestamp.getUTCHours()).padStart(2, "0")}${String(timestamp.getUTCMinutes()).padStart(2, "0")}_${truncated}`;
|
|
235
|
+
}
|
|
236
|
+
//#endregion
|
|
237
|
+
export { materialiseMigrationPackage as a, writeMigrationMetadata as c, materialiseExtensionMigrationPackageIfMissing as i, writeMigrationOps as l, copyFilesWithRename as n, readMigrationPackage as o, formatMigrationDirName as r, readMigrationsDir as s, MANIFEST_FILE as t, writeMigrationPackage as u };
|
|
238
|
+
|
|
239
|
+
//# sourceMappingURL=io-D13dLvUh.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"io-D13dLvUh.mjs","names":[],"sources":["../src/io.ts"],"sourcesContent":["import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';\nimport type {\n MigrationMetadata,\n MigrationPackage,\n} from '@prisma-next/framework-components/control';\nimport { type } from 'arktype';\nimport { basename, dirname, join, resolve } from 'pathe';\nimport { canonicalizeJson } from './canonicalize-json';\nimport {\n errorDirectoryExists,\n errorInvalidDestName,\n errorInvalidJson,\n errorInvalidManifest,\n errorInvalidSlug,\n errorMigrationHashMismatch,\n errorMissingFile,\n errorProvidedInvariantsMismatch,\n} from './errors';\nimport { verifyMigrationHash } from './hash';\nimport { deriveProvidedInvariants } from './invariants';\nimport { MigrationOpsSchema } from './op-schema';\nimport type { MigrationOps, OnDiskMigrationPackage } from './package';\n\nexport const MANIFEST_FILE = 'migration.json';\nconst OPS_FILE = 'ops.json';\nconst MAX_SLUG_LENGTH = 64;\n\nfunction hasErrnoCode(error: unknown, code: string): boolean {\n return error instanceof Error && (error as { code?: string }).code === code;\n}\n\nconst MigrationHintsSchema = type({\n used: 'string[]',\n applied: 'string[]',\n plannerVersion: 'string',\n});\n\nconst MigrationMetadataSchema = type({\n '+': 'reject',\n from: 'string > 0 | null',\n to: 'string',\n migrationHash: 'string',\n fromContract: 'object | null',\n toContract: 'object',\n hints: MigrationHintsSchema,\n labels: 'string[]',\n providedInvariants: 'string[]',\n 'authorship?': type({\n 'author?': 'string',\n 'email?': 'string',\n }),\n 'signature?': type({\n keyId: 'string',\n value: 'string',\n }).or('null'),\n createdAt: 'string',\n});\n\nexport async function writeMigrationPackage(\n dir: string,\n metadata: MigrationMetadata,\n ops: MigrationOps,\n): Promise<void> {\n await mkdir(dirname(dir), { recursive: true });\n\n try {\n await mkdir(dir);\n } catch (error) {\n if (hasErrnoCode(error, 'EEXIST')) {\n throw errorDirectoryExists(dir);\n }\n throw error;\n }\n\n await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(metadata, null, 2), {\n flag: 'wx',\n });\n await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });\n}\n\n/**\n * Materialise an in-memory {@link MigrationPackage} to a per-space\n * directory on disk.\n *\n * Writes three files under `<targetDir>/<pkg.dirName>/`:\n *\n * - `migration.json` — the manifest (pretty-printed, matches\n * {@link writeMigrationPackage}'s output for byte-for-byte parity with\n * app-space migrations).\n * - `ops.json` — the operation list (pretty-printed).\n * - `contract.json` — the canonical-JSON serialisation of\n * `metadata.toContract`. This is the per-package post-state contract\n * snapshot; the canonicalisation pass guarantees byte-determinism so\n * re-emitting the same package across machines / runs produces an\n * identical file.\n *\n * Distinct verb from the lower-level {@link writeMigrationPackage}\n * (which takes constituent `(metadata, ops)`): callers reading\n * `materialise…` know they are persisting a struct-typed package\n * including its contract-snapshot side car.\n *\n * Overwrite-idempotent: the per-package directory is cleared before\n * each emit, so re-running against the same `targetDir` produces\n * byte-identical contents and never leaves stale files behind. The\n * spec's \"re-emitting the same package across runs / machines produces\n * byte-identical files\" guarantee (§ 3) covers both same-dir and\n * fresh-dir re-emits. The lower-level {@link writeMigrationPackage}\n * stays strict because the CLI authoring path (`migration plan` /\n * `migration new`) deliberately refuses to clobber an existing\n * authored migration; this helper is the re-emit path that is\n * supposed to converge on a single canonical on-disk shape.\n *\n * @see specs/framework-mechanism.spec.md § 3 — Emission helper (T1.7).\n */\nexport async function materialiseMigrationPackage(\n targetDir: string,\n pkg: MigrationPackage,\n): Promise<void> {\n const dir = join(targetDir, pkg.dirName);\n await rm(dir, { recursive: true, force: true });\n await writeMigrationPackage(dir, pkg.metadata, pkg.ops);\n await writeFile(join(dir, 'contract.json'), `${canonicalizeJson(pkg.metadata.toContract)}\\n`, {\n flag: 'wx',\n });\n}\n\n/**\n * Idempotent variant of {@link materialiseMigrationPackage}: writes the\n * package only if `<targetDir>/<pkg.dirName>/` does not already exist on\n * disk as a directory; returns `{ written: false }` when the package\n * directory is present (no rewrite, no comparison — by-existence skip).\n *\n * Concretely:\n * - existing directory → skip silently, return `{ written: false }`.\n * - missing path → write three files via {@link materialiseMigrationPackage},\n * return `{ written: true }`.\n * - path exists but is not a directory (file/symlink) → treated as\n * missing; {@link materialiseMigrationPackage} will attempt creation\n * and fail with an appropriate OS error.\n * - any other I/O error from `stat` → propagated unchanged.\n *\n * Used by the CLI's `runContractSpaceExtensionMigrationsPass` to\n * materialise extension migration packages into a project's\n * `migrations/<spaceId>/` directory, and by extension-package tests\n * that mirror the same idempotent-rematerialise property locally\n * without taking a CLI dependency.\n */\nexport async function materialiseExtensionMigrationPackageIfMissing(\n targetDir: string,\n pkg: MigrationPackage,\n): Promise<{ readonly written: boolean }> {\n const pkgDir = join(targetDir, pkg.dirName);\n if (await directoryExists(pkgDir)) {\n return { written: false };\n }\n await materialiseMigrationPackage(targetDir, pkg);\n return { written: true };\n}\n\nasync function directoryExists(p: string): Promise<boolean> {\n try {\n return (await stat(p)).isDirectory();\n } catch (error) {\n if (hasErrnoCode(error, 'ENOENT')) return false;\n throw error;\n }\n}\n\n/**\n * Copy a list of files into `destDir`, optionally renaming each one.\n *\n * The destination directory is created (with `recursive: true`) if it\n * does not already exist. Each source path is copied byte-for-byte into\n * `destDir/<destName>`; missing sources throw `ENOENT`. The helper is\n * intentionally generic: callers own the list of files (e.g. a contract\n * emitter's emitted output) and the naming convention (e.g. renaming\n * the destination contract to `end-contract.*` and the source contract\n * to `start-contract.*`).\n */\nexport async function copyFilesWithRename(\n destDir: string,\n files: readonly { readonly sourcePath: string; readonly destName: string }[],\n): Promise<void> {\n await mkdir(destDir, { recursive: true });\n for (const file of files) {\n if (basename(file.destName) !== file.destName) {\n throw errorInvalidDestName(file.destName);\n }\n await copyFile(file.sourcePath, join(destDir, file.destName));\n }\n}\n\nexport async function writeMigrationMetadata(\n dir: string,\n metadata: MigrationMetadata,\n): Promise<void> {\n await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\\n`);\n}\n\nexport async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {\n await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\\n`);\n}\n\nexport async function readMigrationPackage(dir: string): Promise<OnDiskMigrationPackage> {\n const absoluteDir = resolve(dir);\n const manifestPath = join(absoluteDir, MANIFEST_FILE);\n const opsPath = join(absoluteDir, OPS_FILE);\n\n let manifestRaw: string;\n try {\n manifestRaw = await readFile(manifestPath, 'utf-8');\n } catch (error) {\n if (hasErrnoCode(error, 'ENOENT')) {\n throw errorMissingFile(MANIFEST_FILE, absoluteDir);\n }\n throw error;\n }\n\n let opsRaw: string;\n try {\n opsRaw = await readFile(opsPath, 'utf-8');\n } catch (error) {\n if (hasErrnoCode(error, 'ENOENT')) {\n throw errorMissingFile(OPS_FILE, absoluteDir);\n }\n throw error;\n }\n\n let metadata: MigrationMetadata;\n try {\n metadata = JSON.parse(manifestRaw);\n } catch (e) {\n throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));\n }\n\n let ops: MigrationOps;\n try {\n ops = JSON.parse(opsRaw);\n } catch (e) {\n throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));\n }\n\n validateMetadata(metadata, manifestPath);\n validateOps(ops, opsPath);\n\n // Re-derive before the hash check so format/duplicate diagnostics\n // fire with their dedicated codes rather than as a generic hash mismatch.\n const derivedInvariants = deriveProvidedInvariants(ops);\n if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) {\n throw errorProvidedInvariantsMismatch(\n manifestPath,\n metadata.providedInvariants,\n derivedInvariants,\n );\n }\n\n const pkg: OnDiskMigrationPackage = {\n dirName: basename(absoluteDir),\n dirPath: absoluteDir,\n metadata,\n ops,\n };\n\n const verification = verifyMigrationHash(pkg);\n if (!verification.ok) {\n throw errorMigrationHashMismatch(\n absoluteDir,\n verification.storedHash,\n verification.computedHash,\n );\n }\n\n return pkg;\n}\n\nfunction arraysEqual(a: readonly string[], b: readonly string[]): boolean {\n if (a.length !== b.length) return false;\n for (let i = 0; i < a.length; i++) {\n if (a[i] !== b[i]) return false;\n }\n return true;\n}\n\nfunction validateMetadata(\n metadata: unknown,\n filePath: string,\n): asserts metadata is MigrationMetadata {\n const result = MigrationMetadataSchema(metadata);\n if (result instanceof type.errors) {\n throw errorInvalidManifest(filePath, result.summary);\n }\n}\n\nfunction validateOps(ops: unknown, filePath: string): asserts ops is MigrationOps {\n const result = MigrationOpsSchema(ops);\n if (result instanceof type.errors) {\n throw errorInvalidManifest(filePath, result.summary);\n }\n}\n\nexport async function readMigrationsDir(\n migrationsRoot: string,\n): Promise<readonly OnDiskMigrationPackage[]> {\n let entries: string[];\n try {\n entries = await readdir(migrationsRoot);\n } catch (error) {\n if (hasErrnoCode(error, 'ENOENT')) {\n return [];\n }\n throw error;\n }\n\n const packages: OnDiskMigrationPackage[] = [];\n\n for (const entry of entries.sort()) {\n const entryPath = join(migrationsRoot, entry);\n const entryStat = await stat(entryPath);\n if (!entryStat.isDirectory()) continue;\n\n const manifestPath = join(entryPath, MANIFEST_FILE);\n try {\n await stat(manifestPath);\n } catch {\n continue; // skip non-migration directories\n }\n\n packages.push(await readMigrationPackage(entryPath));\n }\n\n return packages;\n}\n\nexport function formatMigrationDirName(timestamp: Date, slug: string): string {\n const sanitized = slug\n .toLowerCase()\n .replace(/[^a-z0-9]/g, '_')\n .replace(/_+/g, '_')\n .replace(/^_|_$/g, '');\n\n if (sanitized.length === 0) {\n throw errorInvalidSlug(slug);\n }\n\n const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);\n\n const y = timestamp.getUTCFullYear();\n const mo = String(timestamp.getUTCMonth() + 1).padStart(2, '0');\n const d = String(timestamp.getUTCDate()).padStart(2, '0');\n const h = String(timestamp.getUTCHours()).padStart(2, '0');\n const mi = String(timestamp.getUTCMinutes()).padStart(2, '0');\n\n return `${y}${mo}${d}T${h}${mi}_${truncated}`;\n}\n"],"mappings":"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"}
|