@mnmal-ai/substrate 1.0.0-alpha.1 → 1.0.0-alpha.10

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 (47) hide show
  1. package/README.md +48 -6
  2. package/dist/boot-store-BVqfFxh1.js +4060 -0
  3. package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-Cp4PaIYO.d.ts} +2 -87
  4. package/dist/cli-hSCBywhE.js +3126 -0
  5. package/dist/client.d.ts +130 -8
  6. package/dist/client.js +6 -5
  7. package/dist/{plugin-t2g2wX0b.d.ts → dataset-CejF-Fr_.d.ts} +1640 -1320
  8. package/dist/{agent-token-BIboWOU0.js → env-utils-CGNazUNt.js} +31 -2
  9. package/dist/{errors-D4vKuwz8.d.ts → errors-7mycvNGq.d.ts} +1 -1
  10. package/dist/{index-D7mSOFlM.d.ts → index-DgSfwx7M.d.ts} +1 -1
  11. package/dist/node-version-C5FSmwJX.js +26 -0
  12. package/dist/pack.d.ts +2 -2
  13. package/dist/pack.js +1 -1
  14. package/dist/pg-edges-store-Lxsl5ZnK.js +381 -0
  15. package/dist/{plugin-BuQQEzL-.js → plugin-CtwOINCM.js} +171 -18
  16. package/dist/proposals-bootstrap.js +6 -4
  17. package/dist/proposals.config.schema.json +5 -0
  18. package/dist/proposals.d.ts +15 -4
  19. package/dist/proposals.default-config.json +2 -1
  20. package/dist/proposals.js +2 -2
  21. package/dist/recall-bootstrap.js +13 -4
  22. package/dist/recall.config.schema.json +12 -0
  23. package/dist/recall.d.ts +54 -9
  24. package/dist/recall.js +2 -2
  25. package/dist/{repl-C52wyfMs.js → repl-DqfHelK7.js} +62 -29
  26. package/dist/{row-ByLFE2Wx.d.ts → row-BKKCXIG6.d.ts} +5 -3
  27. package/dist/run-B5dTbZ3g.js +1997 -0
  28. package/dist/{schema-g4FQLr0V.d.ts → schema-DoSc-4ig.d.ts} +44 -7
  29. package/dist/script-C6DSa_Na.js +134 -0
  30. package/dist/sdk.d.ts +90 -12
  31. package/dist/sdk.js +5 -110
  32. package/dist/{src-YXlv_RyL.js → src-5SJ5GEIM.js} +1555 -326
  33. package/dist/{src-DuopV8u7.js → src-7CUSMK66.js} +148 -19
  34. package/dist/{src-zcyUofMJ.js → src-Bi849yhn.js} +39 -15
  35. package/dist/{src-5hVbeiAu.js → src-CqT-QWZ_.js} +697 -57
  36. package/dist/src-CyvV7dCK.js +4333 -0
  37. package/dist/{row-DK7lPZVe.js → src-Da0t6si5.js} +11 -11
  38. package/dist/{src-C4DzaIQZ.js → src-hZb8wfvg.js} +12 -1
  39. package/dist/substrate-admin.js +17 -781
  40. package/dist/substrate.js +4 -5476
  41. package/dist/testing.d.ts +557 -8
  42. package/dist/testing.js +39 -3
  43. package/dist/{ws-C72iVS5T.d.ts → ws-ByZyHk7m.d.ts} +3 -3
  44. package/package.json +21 -20
  45. package/dist/dataset-DOXGRz50.js +0 -1535
  46. package/dist/env-utils-B7SGmoeJ.js +0 -21
  47. package/dist/src-CjEwiKXw.js +0 -2327
@@ -0,0 +1,1997 @@
1
+ import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
+ import { h as AUDIT_EVENT_TYPE, m as buildAuditRow } from "./src-5SJ5GEIM.js";
3
+ import { I as decodeList, L as encodeList, M as grantEntryError, g as checkUpdatable, h as checkRevocable, y as newlyGranted } from "./src-Da0t6si5.js";
4
+ import { A as runKeyListViaRoute, B as describeAdminTarget, C as doctorCommand, D as runBootstrap, E as parseBootstrapArgs, F as base64Url, G as USAGE, H as ARGV_SPEC, I as forUpdate, J as pgNoticeOptions, K as argvError, L as generateAdminKeypair, M as ACTOR_HINT, N as BootstrapError, O as REVOKE_EXIT_CODES, P as CLI_ACTOR_KID, R as listActiveAdminKeys, S as grantLines, T as formatBootstrapOutput, U as validateArgv, V as resolveAdminTarget, W as RESTART_NOTE, _ as onboardCommand, b as runRegister, c as refuseContractViolation, g as openPgDataset, h as version, j as runKeyPatchViaRoute, k as UPDATE_EXIT_CODES, l as buildDeferredIndexes, m as loadPluginsFromDir, n as resolvePluginDir, q as AdminCliError, r as BINARY_CONTRACT_VERSION, s as parseEnv, t as bootStore, v as formatRegisterOutput, w as formatDoctorReport, x as runRegisterViaRoute, y as parseRegisterArgs, z as readKeyById } from "./boot-store-BVqfFxh1.js";
5
+ import { a as PLAIN_SCHEMA_NAME, c as assertStoreSchema, d as isDerivedMigration, g as detectLayout, h as UUID_REGEX, i as MIGRATE_STORE_MARKER_TABLE, o as UUID_CHECK_MIGRATION, r as seqName, u as getMigrationList } from "./src-CyvV7dCK.js";
6
+ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
7
+ import { dirname } from "node:path";
8
+ import { createHash, randomUUID } from "node:crypto";
9
+ import { statfs } from "node:fs/promises";
10
+ import postgres from "postgres";
11
+ import { PassThrough, Transform } from "node:stream";
12
+ import { pipeline } from "node:stream/promises";
13
+ import { createInterface } from "node:readline";
14
+
15
+ //#region src/admin/commands/list.ts
16
+ /**
17
+ * `list` — print the active Key rows.
18
+ *
19
+ * Without `--url`: read-only, direct-to-postgres, and it DOES NOT
20
+ * AUTHENTICATE, so an admin row here is no evidence admin auth works — that is
21
+ * `doctor`'s question. With `--url`: an authenticated read through the server.
22
+ */
23
+ /**
24
+ * Parse `list`'s arguments. Returns the `--url` base when one was given.
25
+ */
26
+ function parseListArgs(argv) {
27
+ try {
28
+ return parseListArgsInner(argv);
29
+ } catch (err) {
30
+ if (err instanceof AdminCliError) throw argvError("list", err.message, err.exitCode);
31
+ throw err;
32
+ }
33
+ }
34
+ function parseListArgsInner(argv) {
35
+ validateArgv("list", argv);
36
+ const out = {};
37
+ for (let i = 0; i < argv.length; i++) {
38
+ const tok = argv[i] ?? "";
39
+ if (tok === "--url") {
40
+ const value = argv[i + 1];
41
+ if (value === void 0 || value.startsWith("-")) throw new AdminCliError("list: --url requires a base URL, e.g. --url https://host:3100", 1);
42
+ out.url = value;
43
+ i += 1;
44
+ continue;
45
+ }
46
+ if (tok.startsWith("--url=")) {
47
+ const value = tok.slice(6);
48
+ if (value === "") throw new AdminCliError("list: --url requires a base URL, e.g. --url https://host:3100", 1);
49
+ out.url = value;
50
+ }
51
+ }
52
+ return out;
53
+ }
54
+ async function runList(env, openDataset = openPgDataset) {
55
+ const { dataset, close } = await openDataset(env);
56
+ try {
57
+ const { rows } = await dataset.read("Key", { where: { revokedAt: { eq: null } } });
58
+ const out = [];
59
+ for (const row of rows) {
60
+ const kid = typeof row.kid === "string" ? row.kid : "";
61
+ if (kid.length === 0) continue;
62
+ if (row.revokedAt != null) continue;
63
+ const createdAt = row._metadata?.createdAt ?? "";
64
+ out.push({
65
+ kid,
66
+ name: typeof row.name === "string" ? row.name : "",
67
+ capabilities: typeof row.capabilities === "string" ? row.capabilities : "",
68
+ namespaces: typeof row.namespaces === "string" ? row.namespaces : "",
69
+ createdAt
70
+ });
71
+ }
72
+ return out;
73
+ } finally {
74
+ await close();
75
+ }
76
+ }
77
+ /**
78
+ * Provenance line, printed with every result including the empty one, so an
79
+ * unauthenticated direct read is not mistaken for proof that admin auth works
80
+ * — or, when empty, for proof that the right store is empty.
81
+ */
82
+ const PROVENANCE = "read directly from SUBSTRATE_DATABASE_URL — NOT authenticated, and not a check that any credential works.\nTo ask a running server whether admin auth actually works: substrate-admin doctor --url <base>\n";
83
+ function formatListOutput(rows) {
84
+ if (rows.length === 0) return `no active Key rows\n${PROVENANCE}`;
85
+ return `${formatTable(rows)}${PROVENANCE}`;
86
+ }
87
+ /** The aligned table, shared by both modes so they cannot drift apart. */
88
+ function formatTable(rows) {
89
+ const header = {
90
+ kid: "kid",
91
+ name: "name",
92
+ capabilities: "capabilities",
93
+ namespaces: "namespaces",
94
+ createdAt: "createdAt"
95
+ };
96
+ const all = [header, ...rows];
97
+ const widths = {
98
+ kid: Math.max(...all.map((r) => r.kid.length)),
99
+ name: Math.max(...all.map((r) => r.name.length)),
100
+ capabilities: Math.max(...all.map((r) => r.capabilities.length)),
101
+ namespaces: Math.max(...all.map((r) => r.namespaces.length)),
102
+ createdAt: Math.max(...all.map((r) => r.createdAt.length))
103
+ };
104
+ const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
105
+ const divider = [
106
+ "-".repeat(widths.kid),
107
+ "-".repeat(widths.name),
108
+ "-".repeat(widths.capabilities),
109
+ "-".repeat(widths.namespaces),
110
+ "-".repeat(widths.createdAt)
111
+ ].join(" ");
112
+ const lines = [[
113
+ pad(header.kid, widths.kid),
114
+ pad(header.name, widths.name),
115
+ pad(header.capabilities, widths.capabilities),
116
+ pad(header.namespaces, widths.namespaces),
117
+ pad(header.createdAt, widths.createdAt)
118
+ ].join(" "), divider];
119
+ for (const r of rows) lines.push([
120
+ pad(r.kid, widths.kid),
121
+ pad(r.name, widths.name),
122
+ pad(r.capabilities, widths.capabilities),
123
+ pad(r.namespaces, widths.namespaces),
124
+ pad(r.createdAt, widths.createdAt)
125
+ ].join(" "));
126
+ return `${lines.join("\n")}\n`;
127
+ }
128
+ /**
129
+ * Render the AUTHENTICATED read, naming the target and stating that the
130
+ * server verified the credential before answering.
131
+ */
132
+ function formatRemoteListOutput(rows, baseUrl) {
133
+ const mapped = rows.map((r) => ({
134
+ kid: typeof r.kid === "string" ? r.kid : "",
135
+ name: typeof r.name === "string" ? r.name : "",
136
+ capabilities: typeof r.capabilities === "string" ? r.capabilities : "",
137
+ namespaces: typeof r.namespaces === "string" ? r.namespaces : "",
138
+ createdAt: typeof r.createdAt === "string" ? r.createdAt : ""
139
+ }));
140
+ const provenance = `read from ${baseUrl} over the admin-gated route — AUTHENTICATED, and the server accepted this credential.\n`;
141
+ if (mapped.length === 0) return `no active Key rows\n${provenance}`;
142
+ return `${formatTable(mapped)}${provenance}`;
143
+ }
144
+
145
+ //#endregion
146
+ //#region src/admin/migrate-store/progress.ts
147
+ /** Progress of a migrate-store copy, counted off the COPY text stream as it passes. */
148
+ /**
149
+ * A pass-through that counts rows (one newline each: COPY text escapes the
150
+ * newlines inside values) and reports every `batchRows` rows. A throw from
151
+ * `onProgress` fails the stream, which aborts the copy.
152
+ */
153
+ var RowCounter = class extends Transform {
154
+ table;
155
+ batchRows;
156
+ onProgress;
157
+ rows = 0;
158
+ bytes = 0;
159
+ #next;
160
+ constructor(table, batchRows, onProgress, from = {
161
+ rows: 0,
162
+ bytes: 0
163
+ }) {
164
+ super();
165
+ this.table = table;
166
+ this.batchRows = batchRows;
167
+ this.onProgress = onProgress;
168
+ if (!Number.isInteger(batchRows) || batchRows < 1) throw new Error(`batchRows must be a positive integer (got ${batchRows})`);
169
+ this.rows = from.rows;
170
+ this.bytes = from.bytes;
171
+ this.#next = from.rows - from.rows % batchRows + batchRows;
172
+ }
173
+ _transform(chunk, _enc, cb) {
174
+ try {
175
+ this.bytes += chunk.length;
176
+ for (let i = chunk.indexOf(10); i !== -1; i = chunk.indexOf(10, i + 1)) this.rows++;
177
+ if (this.rows >= this.#next) {
178
+ this.#next = this.rows - this.rows % this.batchRows + this.batchRows;
179
+ this.onProgress({
180
+ table: this.table,
181
+ rows: this.rows,
182
+ bytes: this.bytes,
183
+ done: false
184
+ });
185
+ }
186
+ this.push(chunk);
187
+ cb(null);
188
+ } catch (err) {
189
+ cb(err);
190
+ }
191
+ }
192
+ };
193
+
194
+ //#endregion
195
+ //#region src/admin/migrate-store/copy.ts
196
+ /**
197
+ * The migrate-store copy: streams every planned table from one REPEATABLE
198
+ * READ, READ ONLY source snapshot into a target `bootStore` prepared, with
199
+ * `COPY … TO STDOUT` piped into `COPY … FROM STDIN`. Nothing here writes to
200
+ * the source.
201
+ *
202
+ * Two phases around a re-boot, on one source snapshot. Phase 1 copies the
203
+ * rows (and their shortIds) that declare storage: `_system`,
204
+ * `_system_proposals` and every TypeProposal and FieldProposal. The second
205
+ * boot replays those proposals as serve does, so every proposed type has its
206
+ * partition before phase 2 copies everything else.
207
+ *
208
+ * Progress lives in the marker table on the target. A rerun after an
209
+ * interruption restarts cleanly: it empties the planned tables, keeps the
210
+ * seed rows the first run recorded, and copies again.
211
+ */
212
+ /** A source table or column with nowhere to go on the target. Thrown before any data moves. */
213
+ var MigrateStoreColumnError = class extends Error {
214
+ table;
215
+ column;
216
+ name = "MigrateStoreColumnError";
217
+ constructor(table, column) {
218
+ super(column === null ? `the target has no table "${table}" to copy into` : `the target's "${table}" has no column "${column}", which the source has`);
219
+ this.table = table;
220
+ this.column = column;
221
+ }
222
+ };
223
+ const STARTED = "copy:started";
224
+ const SEED = "seed:";
225
+ /** The `rows` / `short_ids` predicate phase 1 copies; phase 2 copies its complement. Both columns are NOT NULL. */
226
+ const PHASE1_ROWS = "namespace IN ('_system', '_system_proposals') OR type IN ('TypeProposal', 'FieldProposal')";
227
+ const PHASED = /* @__PURE__ */ new Set(["rows", "short_ids"]);
228
+ async function copyStore(source, boot, plan, opts) {
229
+ let target = await boot();
230
+ let open = target;
231
+ try {
232
+ let tsql = sqlOf(target);
233
+ await tsql`CREATE TABLE IF NOT EXISTS ${tsql(MIGRATE_STORE_MARKER_TABLE)} (step text PRIMARY KEY, done_at timestamptz)`;
234
+ const identity = await checkColumns(tsql, plan);
235
+ if (await restartIfStarted(tsql, plan)) {
236
+ open = void 0;
237
+ await target.close();
238
+ target = await boot();
239
+ open = target;
240
+ tsql = sqlOf(target);
241
+ }
242
+ const src = await source.reserve();
243
+ let streaming = false;
244
+ try {
245
+ await src.unsafe("BEGIN ISOLATION LEVEL REPEATABLE READ, READ ONLY");
246
+ const keptSeeds = await reconcileSeeds(src, tsql, target);
247
+ const totals = /* @__PURE__ */ new Map();
248
+ const copy = async (t, filter) => {
249
+ const start = performance.now();
250
+ const prev = totals.get(t.name) ?? {
251
+ rows: 0,
252
+ bytes: 0,
253
+ ms: 0
254
+ };
255
+ const counter = new RowCounter(t.name, opts.batchRows, opts.onProgress, prev);
256
+ streaming = true;
257
+ await copyTable(src, tsql, t, identity.get(t.name) ?? [], counter, filter);
258
+ streaming = false;
259
+ totals.set(t.name, {
260
+ rows: counter.rows,
261
+ bytes: counter.bytes,
262
+ ms: prev.ms + Math.round(performance.now() - start)
263
+ });
264
+ };
265
+ for (const t of plan.tables.filter((p) => PHASED.has(p.name))) await copy(t, PHASE1_ROWS);
266
+ await markStep(tsql, "copy:phase1");
267
+ await snapshotRows(tsql);
268
+ open = void 0;
269
+ await target.close();
270
+ target = await boot();
271
+ open = target;
272
+ tsql = sqlOf(target);
273
+ await assertRebootWroteNothing(tsql);
274
+ const defaulted = await prepareStorage(src, target);
275
+ const tables = [];
276
+ for (const t of plan.tables) {
277
+ await copy(t, PHASED.has(t.name) ? `NOT (${PHASE1_ROWS})` : null);
278
+ await markStep(tsql, `copy:${t.name}`);
279
+ const done = totals.get(t.name);
280
+ tables.push({
281
+ name: t.name,
282
+ ...done
283
+ });
284
+ opts.onProgress({
285
+ table: t.name,
286
+ rows: done.rows,
287
+ bytes: done.bytes,
288
+ done: true
289
+ });
290
+ }
291
+ await markStep(tsql, "copy:phase2");
292
+ await advanceSequences(tsql, identity);
293
+ await markStep(tsql, "copy:done");
294
+ await src.unsafe("COMMIT");
295
+ src.release();
296
+ return {
297
+ tables,
298
+ keptSeeds,
299
+ defaulted,
300
+ target
301
+ };
302
+ } catch (err) {
303
+ const released = src.unsafe("ROLLBACK").catch(() => void 0).then(() => src.release()).catch(() => void 0);
304
+ if (!streaming) await released;
305
+ throw err;
306
+ }
307
+ } catch (err) {
308
+ await open?.close().catch(() => void 0);
309
+ throw err;
310
+ }
311
+ }
312
+ function sqlOf(target) {
313
+ if (target.sql === null) throw new Error("migrate-store copies into a postgres target only");
314
+ return target.sql;
315
+ }
316
+ const SNAPSHOT = "substrate_migrate_store_reboot_rows";
317
+ /** Records every target row's key and content hash, for `assertRebootWroteNothing`. */
318
+ async function snapshotRows(tsql) {
319
+ await tsql`DROP TABLE IF EXISTS ${tsql(SNAPSHOT)}`;
320
+ await tsql`CREATE UNLOGGED TABLE ${tsql(SNAPSHOT)} AS
321
+ SELECT namespace, type, id, md5(r::text) AS h FROM rows r`;
322
+ }
323
+ /** Refuses a re-boot that added, removed or changed a row, naming up to ten of each. */
324
+ async function assertRebootWroteNothing(tsql) {
325
+ const snap = tsql(SNAPSHOT);
326
+ const diff = await tsql`
327
+ SELECT CASE WHEN s.id IS NULL THEN 'added' WHEN r.id IS NULL THEN 'removed' ELSE 'changed' END AS change,
328
+ coalesce(r.namespace, s.namespace) AS namespace, coalesce(r.type, s.type) AS type,
329
+ coalesce(r.id, s.id) AS id
330
+ FROM (SELECT namespace, type, id, md5(x::text) AS h FROM rows x) r
331
+ FULL JOIN ${snap} s USING (namespace, type, id)
332
+ WHERE s.id IS NULL OR r.id IS NULL OR r.h <> s.h
333
+ ORDER BY 1, 2, 3, 4 LIMIT 30`;
334
+ await tsql`DROP TABLE ${snap}`;
335
+ if (diff.length === 0) return;
336
+ const named = [
337
+ "added",
338
+ "changed",
339
+ "removed"
340
+ ].map((c) => {
341
+ const rows = diff.filter((d) => d.change === c).slice(0, 10);
342
+ return rows.length === 0 ? "" : `${c}: ${rows.map((d) => `${d.namespace}/${d.type}/${d.id}`).join(", ")}`;
343
+ }).filter((s) => s !== "").join("; ");
344
+ throw new Error(`the target's re-boot wrote rows the source does not have (${named}). The boot writes them because the source lacks them, usually the _system/AuditEvent of kind 'bootstrap' that serve records on a store's first boot with keys. Boot the source once with substrate serve so it records them itself, stop it, then rerun migrate-store, which restarts cleanly.`);
345
+ }
346
+ /** Refuses a plan column the target lacks; returns each table's identity-always columns among the planned ones. */
347
+ async function checkColumns(tsql, plan) {
348
+ const rows = await tsql`
349
+ SELECT c.relname AS "table", a.attname AS col, a.attidentity AS ident
350
+ FROM pg_attribute a
351
+ JOIN pg_class c ON c.oid = a.attrelid
352
+ JOIN pg_namespace n ON n.oid = c.relnamespace
353
+ WHERE n.nspname = current_schema() AND c.relname = ANY(${plan.tables.map((t) => t.name)}::text[])
354
+ AND c.relkind IN ('r', 'p') AND a.attnum > 0 AND NOT a.attisdropped AND a.attgenerated = ''`;
355
+ const identity = /* @__PURE__ */ new Map();
356
+ for (const t of plan.tables) {
357
+ const cols = rows.filter((r) => r.table === t.name);
358
+ if (cols.length === 0) throw new MigrateStoreColumnError(t.name, null);
359
+ const have = new Set(cols.map((c) => c.col));
360
+ const missing = t.columns.find((c) => !have.has(c));
361
+ if (missing !== void 0) throw new MigrateStoreColumnError(t.name, missing);
362
+ const always = cols.filter((c) => c.ident === "a" && t.columns.includes(c.col));
363
+ if (always.length > 0) identity.set(t.name, always.map((c) => c.col));
364
+ }
365
+ return identity;
366
+ }
367
+ const keyOf = (r) => JSON.stringify([
368
+ r.namespace,
369
+ r.type,
370
+ r.id
371
+ ]);
372
+ /** `(namespace, type, id) IN (…)` over `keys`, as three bound arrays. */
373
+ function inKeys(sql, keys) {
374
+ return sql`(namespace, type, id) IN (SELECT * FROM unnest(
375
+ ${keys.map((k) => k.namespace)}::text[], ${keys.map((k) => k.type)}::text[], ${keys.map((k) => k.id)}::text[]))`;
376
+ }
377
+ /** After an interrupted run: empties every planned table but the seed rows that run recorded. True when it did. */
378
+ async function restartIfStarted(tsql, plan) {
379
+ const marker = tsql(MIGRATE_STORE_MARKER_TABLE);
380
+ const [started] = await tsql`SELECT 1 FROM ${marker} WHERE step = ${STARTED}`;
381
+ if (started === void 0) return false;
382
+ const seeds = (await tsql`SELECT step FROM ${marker} WHERE starts_with(step, ${SEED})`).map((r) => {
383
+ const [namespace, type, id] = JSON.parse(r.step.slice(5));
384
+ return {
385
+ namespace,
386
+ type,
387
+ id
388
+ };
389
+ });
390
+ const others = plan.tables.map((p) => p.name).filter((n) => n !== "rows" && n !== "short_ids");
391
+ await tsql.begin(async (tx) => {
392
+ const t = tx;
393
+ await t`DELETE FROM rows WHERE NOT ${inKeys(t, seeds)}`;
394
+ if (others.length > 0) await t`TRUNCATE ${t(others)}`;
395
+ });
396
+ return true;
397
+ }
398
+ /**
399
+ * Deletes each target row the source also holds, so the source row replaces
400
+ * it, and records the rest as seeds. Every row still on the target must be of
401
+ * a type the target registers, as everything the prepare step writes is.
402
+ */
403
+ async function reconcileSeeds(src, tsql, target) {
404
+ const present = await tsql`SELECT namespace, type, id FROM rows ORDER BY namespace, type, id`;
405
+ const inSource = present.length === 0 ? [] : await src`SELECT namespace, type, id FROM rows WHERE ${inKeys(src, [...present])}`;
406
+ const replaced = new Set(inSource.map(keyOf));
407
+ const kept = present.filter((r) => !replaced.has(keyOf(r))).map(({ namespace, type, id }) => ({
408
+ namespace,
409
+ type,
410
+ id
411
+ }));
412
+ for (const r of kept) if (registeredDataset(target, r.namespace, r.type) === void 0) throw new Error(`target row ${r.namespace}/${r.type}/${r.id} is not one the prepare step wrote; refusing to copy alongside it`);
413
+ const marker = tsql(MIGRATE_STORE_MARKER_TABLE);
414
+ await tsql.begin(async (tx) => {
415
+ const t = tx;
416
+ if (inSource.length > 0) await t`DELETE FROM rows WHERE ${inKeys(t, [...inSource])}`;
417
+ await t`DELETE FROM ${marker} WHERE starts_with(step, ${SEED}) OR starts_with(step, 'copy:')`;
418
+ const steps = [STARTED, ...kept.map((k) => SEED + keyOf(k))];
419
+ await t`INSERT INTO ${marker} ${t(steps.map((step) => ({
420
+ step,
421
+ done_at: /* @__PURE__ */ new Date()
422
+ })))}`;
423
+ });
424
+ return kept;
425
+ }
426
+ function registeredDataset(target, ns, type) {
427
+ if (!target.datasets.has(ns)) return void 0;
428
+ if (target.engine.registryFor(ns)?.get(type)?.kind !== "type") return void 0;
429
+ return target.datasets.get(ns);
430
+ }
431
+ /** Gives every source type the target registers its partition, so its rows never pass through DEFAULT. */
432
+ async function prepareStorage(src, target) {
433
+ const pairs = await src`SELECT DISTINCT namespace, type FROM rows ORDER BY namespace, type`;
434
+ const defaulted = [];
435
+ for (const { namespace, type } of pairs) {
436
+ const dataset = registeredDataset(target, namespace, type);
437
+ if (dataset?.ensureTypeStorage === void 0) {
438
+ defaulted.push({
439
+ namespace,
440
+ type
441
+ });
442
+ continue;
443
+ }
444
+ try {
445
+ await dataset.ensureTypeStorage(type, { indexes: "unique" });
446
+ } catch (err) {
447
+ throw new Error(`preparing storage for ${namespace}/${type} failed: ${err.message}`, { cause: err });
448
+ }
449
+ }
450
+ return defaulted;
451
+ }
452
+ async function copyTable(src, tsql, t, identityCols, counter, filter) {
453
+ const where = filter === null ? src`` : src`WHERE ${src.unsafe(filter)}`;
454
+ const out = await src`COPY (SELECT ${src(t.columns)} FROM ${src(t.name)} ${where}) TO STDOUT`.readable();
455
+ const feed = new PassThrough();
456
+ out.on("error", (err) => feed.destroy(err));
457
+ out.pipe(feed);
458
+ try {
459
+ if (identityCols.length === 0) {
460
+ await copyIn(tsql`COPY ${tsql(t.name)} (${tsql(t.columns)}) FROM STDIN`, feed, counter);
461
+ return;
462
+ }
463
+ await tsql.begin(async (tx) => {
464
+ const x = tx;
465
+ const stage = x(`migrate_stage_${t.name}`);
466
+ await x`CREATE TEMP TABLE ${stage} (LIKE ${x(t.name)} INCLUDING DEFAULTS) ON COMMIT DROP`;
467
+ await copyIn(x`COPY ${stage} (${x(t.columns)}) FROM STDIN`, feed, counter);
468
+ await x`INSERT INTO ${x(t.name)} (${x(t.columns)}) OVERRIDING SYSTEM VALUE SELECT ${x(t.columns)} FROM ${stage}`;
469
+ });
470
+ } catch (err) {
471
+ out.unpipe(feed);
472
+ feed.destroy();
473
+ out.resume();
474
+ const detail = err.detail;
475
+ throw new Error(`copying ${t.name} failed: ${err.message}${detail ? ` (${detail})` : ""}`, { cause: err });
476
+ }
477
+ }
478
+ /**
479
+ * Pipes `feed` through `counter` into a `COPY … FROM STDIN`. postgres.js 3.4.9
480
+ * never finishes the writable when the server rejects the COPY, so the
481
+ * query's own reject is raced as the failure signal.
482
+ */
483
+ async function copyIn(query, feed, counter) {
484
+ const q = query;
485
+ const reject = q.reject;
486
+ const failed = new Promise((_, fail) => {
487
+ q.reject = (err) => {
488
+ fail(err);
489
+ reject(err);
490
+ };
491
+ });
492
+ failed.catch(() => void 0);
493
+ const into = await query.writable();
494
+ await Promise.race([pipeline(feed, counter, into), failed]);
495
+ }
496
+ /**
497
+ * Moves every shortId sequence to the highest copied shortId of the
498
+ * (namespace, type) pairs sharing its name, creating it if missing, and every
499
+ * copied identity column's sequence to its column's maximum.
500
+ */
501
+ async function advanceSequences(tsql, identity) {
502
+ const maxes = await tsql`SELECT namespace, type, max(short_id)::text AS max FROM short_ids GROUP BY namespace, type`;
503
+ const byName = /* @__PURE__ */ new Map();
504
+ for (const m of maxes) {
505
+ const name = seqName(m.namespace, m.type);
506
+ const max = BigInt(m.max);
507
+ if ((byName.get(name) ?? 0n) < max) byName.set(name, max);
508
+ }
509
+ for (const [name, max] of byName) {
510
+ await tsql`CREATE SEQUENCE IF NOT EXISTS ${tsql(name)}`;
511
+ await tsql`SELECT setval(${`"${name}"`}::regclass, ${max.toString()}::bigint)`;
512
+ }
513
+ for (const [table, cols] of identity) for (const col of cols) await tsql`
514
+ SELECT setval(pg_get_serial_sequence(quote_ident(${table}), ${col}), m)
515
+ FROM (SELECT max(${tsql(col)}) AS m FROM ${tsql(table)}) s WHERE m IS NOT NULL`;
516
+ }
517
+ async function markStep(tsql, step) {
518
+ await tsql`
519
+ INSERT INTO ${tsql(MIGRATE_STORE_MARKER_TABLE)} (step, done_at) VALUES (${step}, now())
520
+ ON CONFLICT (step) DO UPDATE SET done_at = excluded.done_at`;
521
+ }
522
+
523
+ //#endregion
524
+ //#region src/admin/migrate-store/source.ts
525
+ /**
526
+ * Read-only inventory of a migrate-store source. Every read runs in one
527
+ * REPEATABLE READ, READ ONLY transaction, so the inventory is one snapshot and
528
+ * nothing here can write to the source. It never runs migrations and never
529
+ * goes through `assertServerVersion`: the source may be PG 17.
530
+ */
531
+ async function inspectSource(sql) {
532
+ return await sql.begin("isolation level repeatable read read only", async (tx) => {
533
+ await assertStoreSchema(tx);
534
+ const layout = await detectLayout(tx);
535
+ if (layout === "absent") throw new Error("the source schema holds no rows table");
536
+ const [version] = await tx`SELECT current_setting('server_version_num')::int AS v`;
537
+ const [ledger] = await tx`SELECT to_regclass('migrations') IS NOT NULL AS present`;
538
+ const appliedMigrations = ledger?.present ? (await tx`SELECT version FROM migrations ORDER BY version`).map((r) => r.version) : [];
539
+ const tableRows = await tx`
540
+ SELECT c.relname AS name,
541
+ -- pg_partition_tree is empty for an ordinary table.
542
+ (CASE WHEN c.relkind = 'p'
543
+ THEN (SELECT coalesce(sum(pg_table_size(t.relid)), 0) FROM pg_partition_tree(c.oid) t WHERE t.isleaf)
544
+ ELSE pg_table_size(c.oid) END)::text AS bytes
545
+ FROM pg_class c
546
+ WHERE c.relnamespace = current_schema()::regnamespace
547
+ AND c.relkind IN ('r', 'p') AND NOT c.relispartition
548
+ ORDER BY c.relname`;
549
+ const colRows = await tx`
550
+ SELECT c.relname AS "table", a.attname AS col
551
+ FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid
552
+ WHERE c.relnamespace = current_schema()::regnamespace
553
+ AND c.relkind IN ('r', 'p') AND NOT c.relispartition
554
+ AND a.attnum > 0 AND NOT a.attisdropped AND a.attgenerated = ''
555
+ ORDER BY c.relname, a.attnum`;
556
+ const columns = {};
557
+ for (const r of colRows) {
558
+ const list = columns[r.table] ?? [];
559
+ list.push(r.col);
560
+ columns[r.table] = list;
561
+ }
562
+ const types = await tx`
563
+ SELECT namespace, type,
564
+ count(*) FILTER (WHERE deleted_at IS NULL)::text AS live,
565
+ count(*) FILTER (WHERE deleted_at IS NOT NULL)::text AS deleted,
566
+ coalesce(sum(pg_column_size(r.*)), 0)::text AS bytes
567
+ FROM rows r GROUP BY namespace, type ORDER BY namespace, type`;
568
+ const nonUuid = (table, column, nsCol, typeCol) => tx`
569
+ SELECT ${tx(nsCol)} AS namespace, ${tx(typeCol)} AS type, ${tx(column)} AS id
570
+ FROM ${tx(table)} WHERE ${tx(column)} !~ ${UUID_REGEX}
571
+ ORDER BY 1, 2, 3 LIMIT 20`.then((rs) => rs.map((r) => ({
572
+ table,
573
+ column,
574
+ ...r
575
+ })));
576
+ const nonUuidIds = appliedMigrations.includes("0002_uuid_format_check") ? [] : [
577
+ ...await nonUuid("rows", "id", "namespace", "type"),
578
+ ...columns.short_ids ? await nonUuid("short_ids", "row_id", "namespace", "type") : [],
579
+ ...columns.edges ? await nonUuid("edges", "from_id", "from_ns", "from_type") : [],
580
+ ...columns.edges ? await nonUuid("edges", "to_id", "to_ns", "to_type") : []
581
+ ];
582
+ const [dims] = columns.embeddings ? await tx`
583
+ SELECT a.atttypmod AS dims FROM pg_attribute a
584
+ WHERE a.attrelid = to_regclass('embeddings') AND a.attname = 'embedding' AND NOT a.attisdropped` : [];
585
+ const extensions = await tx`SELECT extname, extversion FROM pg_extension ORDER BY extname`;
586
+ const [others] = await tx`
587
+ SELECT count(*)::text AS n FROM pg_stat_activity
588
+ WHERE datname = current_database() AND pid <> pg_backend_pid() AND backend_type = 'client backend'`;
589
+ return {
590
+ serverVersionNum: version?.v ?? 0,
591
+ layout,
592
+ appliedMigrations,
593
+ hasSeq: columns.rows?.includes("seq") ?? false,
594
+ hasVisibleSeqs: columns.visible_seqs !== void 0,
595
+ types: types.map((t) => ({
596
+ ...t,
597
+ live: Number(t.live),
598
+ deleted: Number(t.deleted),
599
+ bytes: Number(t.bytes)
600
+ })),
601
+ tables: tableRows.map((t) => t.name),
602
+ columns,
603
+ tableBytes: Object.fromEntries(tableRows.map((t) => [t.name, Number(t.bytes)])),
604
+ nonUuidIds,
605
+ vectorDims: dims !== void 0 && dims.dims > 0 ? dims.dims : null,
606
+ extensions: Object.fromEntries(extensions.map((e) => [e.extname, e.extversion])),
607
+ otherSessions: Number(others?.n ?? 0)
608
+ };
609
+ });
610
+ }
611
+
612
+ //#endregion
613
+ //#region src/admin/migrate-store/preflight.ts
614
+ /** Pure preflight: turns a source inventory plus target facts into refusals, warnings and a copy plan. */
615
+ const ENGINE_COPIED = [
616
+ "rows",
617
+ "short_ids",
618
+ "edges",
619
+ "visible_seqs"
620
+ ];
621
+ const NOT_COPIED = [
622
+ "idempotency",
623
+ "migrations",
624
+ "migrations_audit",
625
+ "kernel_migrations",
626
+ MIGRATE_STORE_MARKER_TABLE
627
+ ];
628
+ /** The extension a copied table depends on. shortcut: recall's only, upgrade when another plugin table needs one. */
629
+ const TABLE_EXTENSION = { embeddings: "vector" };
630
+ const PG17 = 17e4;
631
+ const PG18 = 18e4;
632
+ function preflight(source, target, opts) {
633
+ const refusals = [];
634
+ const warnings = [];
635
+ if (source.serverVersionNum < PG17) refusals.push(`source is PostgreSQL ${source.serverVersionNum} (server_version_num); 170000 or later is required`);
636
+ if (target.serverVersionNum < PG18) refusals.push(`target is PostgreSQL ${target.serverVersionNum} (server_version_num); 180000 or later is required`);
637
+ const baselines = [getMigrationList(true, "legacy")[0], getMigrationList(true, "partitioned")[0]].map((m) => m?.version);
638
+ const known = new Set([...getMigrationList(true, "legacy"), ...getMigrationList(true, "partitioned")].map((m) => m.version));
639
+ const unknownVersions = source.appliedMigrations.filter((v) => !known.has(v) && !isDerivedMigration(v));
640
+ if (unknownVersions.length > 0) refusals.push(`source ledger holds migrations this binary does not know: ${unknownVersions.join(", ")}`);
641
+ if (!source.appliedMigrations.some((v) => baselines.includes(v))) refusals.push(`source ledger lacks ${baselines.join(" / ")}; found: ${source.appliedMigrations.join(", ") || "no migrations"}`);
642
+ if (!target.empty && !target.createdByUs) refusals.push("target already holds data and was not created by migrate-store");
643
+ const otherBaseline = baselines.find((b) => b !== getMigrationList(true, source.layout)[0]?.version);
644
+ if (otherBaseline !== void 0 && source.appliedMigrations.includes(otherBaseline)) refusals.push(`source ledger records ${otherBaseline} but rows is ${source.layout}`);
645
+ if (source.appliedMigrations.includes("0002_uuid_format_check") && !target.enforceUuidCheck) refusals.push(`source enforces the UUID check (${UUID_CHECK_MIGRATION}) but the target would not: run migrate-store with the service's environment, which sets SUBSTRATE_ENFORCE_UUID_CHECK=true`);
646
+ if (target.enforceUuidCheck && source.nonUuidIds.length > 0) {
647
+ const sample = source.nonUuidIds.slice(0, 5).map((r) => `${r.table}.${r.column}=${r.id}`).join(", ");
648
+ refusals.push(`source has ${source.nonUuidIds.length} non-UUID id(s) while the target enforces the UUID check (first 5 shown): ${sample}`);
649
+ }
650
+ const skip = new Set(opts.skipTables);
651
+ const knownTables = /* @__PURE__ */ new Set([
652
+ ...ENGINE_COPIED,
653
+ ...NOT_COPIED,
654
+ ...opts.pluginTables
655
+ ]);
656
+ const unknownTables = source.tables.filter((t) => !knownTables.has(t) && !skip.has(t));
657
+ for (const t of unknownTables) refusals.push(`source table "${t}" is not known to migrate-store; load the plugin that owns it, or pass --skip-table ${t}`);
658
+ for (const t of skip) if (!source.tables.includes(t)) warnings.push(`--skip-table ${t} matches no source table`);
659
+ if (source.vectorDims !== null && target.recallDims !== null && source.vectorDims !== target.recallDims) refusals.push(`recall embedding dimensions differ: source ${source.vectorDims}, target ${target.recallDims}`);
660
+ const present = new Set(source.tables);
661
+ const plan = {
662
+ tables: [...ENGINE_COPIED, ...opts.pluginTables].filter((t, i, all) => present.has(t) && all.indexOf(t) === i).map((name) => ({
663
+ name,
664
+ columns: source.columns[name] ?? [],
665
+ bytes: source.tableBytes[name] ?? 0
666
+ })),
667
+ estimatedBytes: 0,
668
+ skipped: [...skip].filter((t) => present.has(t))
669
+ };
670
+ plan.estimatedBytes = 2 * plan.tables.reduce((n, t) => n + t.bytes, 0);
671
+ for (const t of plan.tables) {
672
+ const ext = TABLE_EXTENSION[t.name];
673
+ if (ext === void 0) continue;
674
+ const [from, to] = [source.extensions[ext], target.extensions[ext]];
675
+ if (to === void 0) refusals.push(`table "${t.name}" needs extension "${ext}", which is not installed in a schema on the target's search_path; run CREATE EXTENSION ${ext}; in the target database as a superuser, in public or the target schema`);
676
+ else if (from !== void 0 && from !== to) warnings.push(`extension "${ext}" is version ${from} on the source and ${to} on the target, so verification of ${t.name} may fail; match the versions`);
677
+ }
678
+ if (target.freeBytes !== null && target.freeBytes < plan.estimatedBytes) {
679
+ const msg = `free disk ${target.freeBytes} bytes is below the estimated need of ${plan.estimatedBytes} bytes`;
680
+ (opts.dryRun ? warnings : refusals).push(msg);
681
+ }
682
+ if (source.otherSessions > 0) warnings.push(`source has ${source.otherSessions} other active session(s) on its database; writes after the snapshot are not copied, so stop the service first`);
683
+ return {
684
+ refusals,
685
+ warnings,
686
+ plan
687
+ };
688
+ }
689
+
690
+ //#endregion
691
+ //#region src/admin/migrate-store/verify.ts
692
+ /**
693
+ * The migrate-store verification: compares the source and the copy per
694
+ * (namespace, type) and, only when everything agrees, drops the in-progress
695
+ * marker so `serve` will boot the target. Both sides are read in their own
696
+ * REPEATABLE READ, READ ONLY transaction; nothing here writes to the source.
697
+ *
698
+ * Target rows the prepare step seeded and the source lacks (`keptSeeds`) are
699
+ * subtracted from the target side before every comparison.
700
+ *
701
+ * Every set is fingerprinted as `count(*)` plus the sum of a 64-bit prefix of
702
+ * each row's md5. That is independent of row order, of either cluster's
703
+ * collation, and of any join separator, and it builds no string.
704
+ */
705
+ const quote = (cols) => cols.map((c) => `"${c.replace(/"/g, "\"\"")}"`).join(", ");
706
+ /** SQL for a set's fingerprint: its size and an order-independent sum of per-row hashes of `expr`. */
707
+ const fp = (expr) => `count(*)::text || ' ' || coalesce(sum(('x' || substr(md5(${expr}), 1, 16))::bit(64)::bigint::numeric), 0)::text`;
708
+ async function verifyStore(source, target, opts) {
709
+ const readOnly = "isolation level repeatable read read only";
710
+ const src = await source.begin(readOnly, (tx) => snapshot(tx, [], null, opts));
711
+ const tgt = await target.begin(readOnly, (tx) => snapshot(tx, opts.keptSeeds, src, opts));
712
+ const mismatches = [];
713
+ const keys = [.../* @__PURE__ */ new Set([...src.entries.keys(), ...tgt.entries.keys()])].sort();
714
+ for (const k of keys) {
715
+ const a = src.entries.get(k);
716
+ const b = tgt.entries.get(k);
717
+ if (a?.value === b?.value) continue;
718
+ const e = a ?? b;
719
+ mismatches.push({
720
+ check: e.check,
721
+ ...e.namespace !== void 0 ? { namespace: e.namespace } : {},
722
+ ...e.type !== void 0 ? { type: e.type } : {},
723
+ detail: `${e.what}: source ${a?.value ?? "absent"}, target ${b?.value ?? "absent"}`
724
+ });
725
+ }
726
+ const expected = new Set(opts.defaulted.map((d) => JSON.stringify([d.namespace, d.type])));
727
+ for (const w of (await opts.storageReport({ partitionBudget: opts.partitionBudget })).warnings) {
728
+ const m = /^\S+ holds \d+ rows of (.+)\/([^/]+)$/.exec(w);
729
+ if (m !== null && expected.has(JSON.stringify([m[1], m[2]]))) continue;
730
+ mismatches.push({
731
+ check: "storage",
732
+ ...m !== null ? {
733
+ namespace: m[1],
734
+ type: m[2]
735
+ } : {},
736
+ detail: w
737
+ });
738
+ }
739
+ const ok = mismatches.length === 0;
740
+ if (ok) await target`DROP TABLE IF EXISTS ${target(MIGRATE_STORE_MARKER_TABLE)}`;
741
+ return {
742
+ ok,
743
+ mismatches
744
+ };
745
+ }
746
+ const COPY_MILESTONES = /* @__PURE__ */ new Set([
747
+ "copy:started",
748
+ "copy:phase1",
749
+ "copy:phase2",
750
+ "copy:done"
751
+ ]);
752
+ /**
753
+ * What a finished copy left behind, for a verification that has no
754
+ * `CopyResult`: the kept seeds from the marker table, and the types the target
755
+ * does not register (their rows sit in a DEFAULT partition), and the copied
756
+ * tables, which are the marker's `copy:<table>` steps.
757
+ */
758
+ async function readCopyState(target) {
759
+ const sql = target.sql;
760
+ if (sql === null) throw new Error("migrate-store verifies a postgres target only");
761
+ const steps = await sql`
762
+ SELECT step FROM ${sql(MIGRATE_STORE_MARKER_TABLE)}`.catch((err) => {
763
+ if (err.code === "42P01") return [];
764
+ throw err;
765
+ });
766
+ if (!steps.some((s) => s.step === "copy:done")) throw new Error("the target has no completed migrate-store copy to verify (its in-progress marker is missing or the copy did not finish)");
767
+ return {
768
+ keptSeeds: steps.filter((s) => s.step.startsWith(SEED)).map((s) => {
769
+ const [namespace, type, id] = JSON.parse(s.step.slice(SEED.length));
770
+ return {
771
+ namespace,
772
+ type,
773
+ id
774
+ };
775
+ }).sort((a, b) => (a.namespace + a.type + a.id).localeCompare(b.namespace + b.type + b.id)),
776
+ defaulted: (await sql`SELECT DISTINCT namespace, type FROM rows ORDER BY namespace, type`).filter((p) => registeredDataset(target, p.namespace, p.type)?.ensureTypeStorage === void 0),
777
+ tables: steps.map((s) => s.step).filter((s) => s.startsWith("copy:") && !COPY_MILESTONES.has(s)).map((s) => s.slice(5)).sort()
778
+ };
779
+ }
780
+ /** Every comparable fact about one side, keyed so the two sides diff by key. `other` is the source's snapshot when this is the target. */
781
+ async function snapshot(tx, seeds, other, opts) {
782
+ await tx`SET LOCAL TimeZone = 'UTC'`;
783
+ await tx`SET LOCAL DateStyle = 'ISO, YMD'`;
784
+ await tx`SET LOCAL extra_float_digits = 3`;
785
+ const entries = /* @__PURE__ */ new Map();
786
+ const columns = /* @__PURE__ */ new Map();
787
+ const add = (e) => entries.set(`${e.check}\0${e.namespace ?? ""}\0${e.type ?? ""}\0${e.what}`, e);
788
+ const notSeed = (ns, ty, id) => tx`(${tx(ns)}, ${tx(ty)}, ${tx(id)}) NOT IN (SELECT * FROM unnest(
789
+ ${seeds.map((k) => k.namespace)}::text[], ${seeds.map((k) => k.type)}::text[], ${seeds.map((k) => k.id)}::text[]))`;
790
+ const colsOf = async (table) => {
791
+ const have = await tx`
792
+ SELECT a.attname AS col FROM pg_attribute a
793
+ WHERE a.attrelid = to_regclass(${table}) AND a.attnum > 0 AND NOT a.attisdropped AND a.attgenerated = ''
794
+ ORDER BY a.attname`;
795
+ if (have.length === 0) return null;
796
+ const theirs = other?.columns.get(table);
797
+ const cols = have.map((c) => c.col).filter((c) => theirs === void 0 || theirs.includes(c));
798
+ columns.set(table, cols);
799
+ return cols;
800
+ };
801
+ const counts = await tx`
802
+ SELECT namespace, type,
803
+ count(*) FILTER (WHERE deleted_at IS NULL)::text AS live,
804
+ count(*) FILTER (WHERE deleted_at IS NOT NULL)::text AS deleted,
805
+ ${tx.unsafe(fp("id"))} AS ids
806
+ FROM rows WHERE ${notSeed("namespace", "type", "id")} GROUP BY namespace, type`;
807
+ for (const r of counts) {
808
+ const at = {
809
+ namespace: r.namespace,
810
+ type: r.type
811
+ };
812
+ add({
813
+ check: "count",
814
+ ...at,
815
+ what: "live rows",
816
+ value: r.live
817
+ });
818
+ add({
819
+ check: "count",
820
+ ...at,
821
+ what: "deleted rows",
822
+ value: r.deleted
823
+ });
824
+ add({
825
+ check: "ids",
826
+ ...at,
827
+ what: "id set",
828
+ value: r.ids
829
+ });
830
+ }
831
+ const shorts = await tx`
832
+ SELECT namespace, type, ${tx.unsafe(fp("row(short_id, row_id)::text"))} AS f
833
+ FROM short_ids WHERE ${notSeed("namespace", "type", "row_id")} GROUP BY namespace, type`;
834
+ for (const r of shorts) add({
835
+ check: "short_ids",
836
+ namespace: r.namespace,
837
+ type: r.type,
838
+ what: "shortIds",
839
+ value: r.f
840
+ });
841
+ const edgeCols = await colsOf("edges");
842
+ if (edgeCols !== null) {
843
+ const edges = await tx`
844
+ SELECT from_ns AS namespace, from_type AS type, field_name AS field,
845
+ ${tx.unsafe(fp(`row(${quote(edgeCols)})::text`))} AS f
846
+ FROM edges WHERE ${notSeed("from_ns", "from_type", "from_id")} GROUP BY from_ns, from_type, field_name`;
847
+ for (const r of edges) add({
848
+ check: "edges",
849
+ namespace: r.namespace,
850
+ type: r.type,
851
+ what: `edges of ${r.field}`,
852
+ value: r.f
853
+ });
854
+ }
855
+ const rowCols = await colsOf("rows");
856
+ const limit = opts.fullChecksum ? 2147483647 : opts.sampleRows;
857
+ for (const { namespace, type } of counts) {
858
+ const [r] = await tx`
859
+ SELECT ${tx.unsafe(fp("h"))} AS f FROM (
860
+ SELECT row(${tx.unsafe(quote(rowCols))})::text AS h FROM rows
861
+ WHERE namespace = ${namespace} AND type = ${type} AND ${notSeed("namespace", "type", "id")}
862
+ ORDER BY md5(id) COLLATE "C" LIMIT ${limit}) s`;
863
+ add({
864
+ check: "sample",
865
+ namespace,
866
+ type,
867
+ what: "content",
868
+ value: String(r?.f)
869
+ });
870
+ }
871
+ const skip = /* @__PURE__ */ new Set([
872
+ "rows",
873
+ "short_ids",
874
+ "edges"
875
+ ]);
876
+ for (const name of opts.tables.filter((t) => !skip.has(t))) {
877
+ if (other !== null && !other.columns.has(name)) continue;
878
+ const cols = await colsOf(name);
879
+ if (cols === null) continue;
880
+ const where = [
881
+ "row_namespace",
882
+ "row_type",
883
+ "row_id"
884
+ ].every((c) => cols.includes(c)) ? notSeed("row_namespace", "row_type", "row_id") : tx`true`;
885
+ const [r] = await tx`
886
+ SELECT ${tx.unsafe(fp(`row(${quote(cols)})::text`))} AS f FROM ${tx(name)} WHERE ${where}`;
887
+ add({
888
+ check: "table",
889
+ what: name,
890
+ value: String(r?.f)
891
+ });
892
+ }
893
+ return {
894
+ entries,
895
+ columns
896
+ };
897
+ }
898
+
899
+ //#endregion
900
+ //#region src/admin/commands/migrate-store.ts
901
+ /**
902
+ * `substrate-admin migrate-store`: copies a store into a fresh, empty,
903
+ * partitioned PostgreSQL 18 store. Preflight, prepare and copy, index builds,
904
+ * verification, report. Connection strings come from named environment
905
+ * variables only, and nothing this command prints carries one.
906
+ */
907
+ const DEFAULT_FROM_ENV = "SUBSTRATE_MIGRATE_FROM_URL";
908
+ const DEFAULT_TO_ENV = "SUBSTRATE_MIGRATE_TO_URL";
909
+ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
910
+ const IDENT = PLAIN_SCHEMA_NAME;
911
+ const SAFE_VALUE = (flag) => `migrate-store: ${flag} takes a plain name (a value that does not fit is not echoed)`;
912
+ /** Parses the argv tail after `migrate-store`. Usage errors exit 2. */
913
+ function parseMigrateStoreArgs(tail) {
914
+ validateArgv("migrate-store", tail);
915
+ const seen = /* @__PURE__ */ new Map();
916
+ const args = {
917
+ fromEnv: DEFAULT_FROM_ENV,
918
+ toEnv: DEFAULT_TO_ENV,
919
+ fromSchema: null,
920
+ toSchema: null,
921
+ batchRows: 1e4,
922
+ skipTables: [],
923
+ dryRun: false,
924
+ verifyOnly: false,
925
+ json: false,
926
+ skipIndexBuild: false,
927
+ fullChecksum: false
928
+ };
929
+ const fail = (msg) => argvError("migrate-store", msg, 2);
930
+ for (let i = 0; i < tail.length; i++) {
931
+ const tok = tail[i];
932
+ switch (tok) {
933
+ case "--dry-run":
934
+ args.dryRun = true;
935
+ continue;
936
+ case "--verify-only":
937
+ args.verifyOnly = true;
938
+ continue;
939
+ case "--json":
940
+ args.json = true;
941
+ continue;
942
+ case "--skip-index-build":
943
+ args.skipIndexBuild = true;
944
+ continue;
945
+ case "--full-checksum":
946
+ args.fullChecksum = true;
947
+ continue;
948
+ }
949
+ const value = tail[i + 1];
950
+ if (value === void 0 || value.startsWith("--")) throw fail(`migrate-store: ${tok} needs a value`);
951
+ i += 1;
952
+ if (tok !== "--skip-table") {
953
+ if (seen.has(tok)) throw fail(`migrate-store: ${tok} given more than once`);
954
+ seen.set(tok, value);
955
+ }
956
+ switch (tok) {
957
+ case "--from-env":
958
+ case "--to-env":
959
+ if (!ENV_NAME.test(value)) throw fail(`migrate-store: ${tok} takes the NAME of an environment variable that holds the connection string, never the string itself`);
960
+ args[tok === "--from-env" ? "fromEnv" : "toEnv"] = value;
961
+ break;
962
+ case "--from-schema":
963
+ case "--to-schema":
964
+ if (!IDENT.test(value)) throw fail(SAFE_VALUE(tok));
965
+ args[tok === "--from-schema" ? "fromSchema" : "toSchema"] = value;
966
+ break;
967
+ case "--skip-table":
968
+ if (!IDENT.test(value)) throw fail(SAFE_VALUE(tok));
969
+ args.skipTables.push(value);
970
+ break;
971
+ case "--batch-rows": {
972
+ const n = Number(value);
973
+ if (!/^\d+$/.test(value) || !Number.isSafeInteger(n) || n < 1) throw fail("migrate-store: --batch-rows takes a positive integer");
974
+ args.batchRows = n;
975
+ break;
976
+ }
977
+ }
978
+ }
979
+ if (args.dryRun && args.verifyOnly) throw fail("migrate-store: --dry-run and --verify-only are mutually exclusive");
980
+ return args;
981
+ }
982
+ /** Replaces every URL, and each given secret, in `s`. */
983
+ function redactor(secrets) {
984
+ const literals = [...new Set(secrets.filter((x) => x.length >= 3))].sort((a, b) => b.length - a.length);
985
+ return (s) => {
986
+ let r = s.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s'"`]+/gi, "<redacted url>");
987
+ for (const l of literals) r = r.split(l).join("<redacted>");
988
+ return r;
989
+ };
990
+ }
991
+ /** The connection string, its password both as written and decoded, for `redactor`. */
992
+ function secretsOf(url) {
993
+ if (url === void 0 || url.length === 0) return [];
994
+ const out = [url];
995
+ let pw = "";
996
+ try {
997
+ pw = new URL(url).password;
998
+ } catch {}
999
+ if (pw.length === 0) return out;
1000
+ out.push(pw);
1001
+ try {
1002
+ out.push(decodeURIComponent(pw));
1003
+ } catch {}
1004
+ return out;
1005
+ }
1006
+ /** `url` with `search_path` pinned to `schema`, as a startup option so every pooled connection has it. */
1007
+ function withSchema(url, schema) {
1008
+ return schema === null ? url : withSettings(url, [`search_path=${schema},public`]);
1009
+ }
1010
+ /** `url` with each `name=value` in `settings` as a startup option (`-c`). */
1011
+ function withSettings(url, settings) {
1012
+ const u = new URL(url);
1013
+ const prior = u.searchParams.get("options");
1014
+ const params = [...u.searchParams.entries()].filter(([k]) => k !== "options");
1015
+ const added = settings.map((s) => `-c ${s}`).join(" ");
1016
+ params.push(["options", `${prior !== null ? `${prior} ` : ""}${added}`]);
1017
+ u.search = params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
1018
+ return u.toString();
1019
+ }
1020
+ const DISK_PATH_UNSET = "SUBSTRATE_INDEX_DISK_PATH is unset, so the target cannot check free disk before index builds and its storage check fails verification: set it to the target database volume mount, or to off when the database has no local volume";
1021
+ const PENDING_INDEX = /^index \S+ on \S+ is pending( \(.*\))?: filters it would serve scan until it is valid$/;
1022
+ async function runMigrateStore(args, env, deps) {
1023
+ const started = performance.now();
1024
+ const vars = env;
1025
+ const urlOf = (name, side) => {
1026
+ const v = vars[name]?.trim();
1027
+ if (v === void 0 || v.length === 0) throw new AdminCliError(`migrate-store: ${name} (the ${side} connection string) is not set`, 2);
1028
+ if (!/^postgres(ql)?:\/\//.test(v)) throw new AdminCliError(`migrate-store: ${name} does not hold a postgres:// connection string`, 2);
1029
+ return v;
1030
+ };
1031
+ const fromUrl = withSchema(urlOf(args.fromEnv, "source"), args.fromSchema);
1032
+ const toStore = withSchema(urlOf(args.toEnv, "target"), args.toSchema);
1033
+ if (fromUrl === toStore) throw new AdminCliError("migrate-store: the source and the target are the same store", 2);
1034
+ const toUrl = withSettings(toStore, ["statement_timeout=0"]);
1035
+ const report = {
1036
+ mode: args.dryRun ? "dry-run" : args.verifyOnly ? "verify-only" : "migrate",
1037
+ ok: false,
1038
+ exitCode: 2,
1039
+ refusals: [],
1040
+ warnings: [],
1041
+ tables: [],
1042
+ phases: {},
1043
+ totalMs: 0,
1044
+ keptSeeds: [],
1045
+ defaulted: [],
1046
+ pendingIndexes: [],
1047
+ mismatches: [],
1048
+ switchOver: null
1049
+ };
1050
+ const finish = (exitCode) => {
1051
+ report.exitCode = exitCode;
1052
+ report.ok = exitCode === 0;
1053
+ report.totalMs = Math.round(performance.now() - started);
1054
+ return report;
1055
+ };
1056
+ const phase = async (name, fn) => {
1057
+ deps.progress(`migrate-store: ${name}`);
1058
+ const t = performance.now();
1059
+ try {
1060
+ return await fn();
1061
+ } finally {
1062
+ report.phases[name] = Math.round(performance.now() - t);
1063
+ }
1064
+ };
1065
+ const diskPath = vars.SUBSTRATE_INDEX_DISK_PATH?.trim();
1066
+ if (diskPath === void 0 || diskPath.length === 0) (args.dryRun ? report.warnings : report.refusals).push(DISK_PATH_UNSET);
1067
+ if (report.refusals.length > 0) return finish(2);
1068
+ const targetEnv = {
1069
+ ...vars,
1070
+ SUBSTRATE_DATABASE_URL: toUrl
1071
+ };
1072
+ const pluginDir = resolvePluginDir(targetEnv);
1073
+ const boot = () => bootStore({
1074
+ config: parseEnv(targetEnv),
1075
+ pluginDir,
1076
+ layout: "partitioned",
1077
+ allowMigrating: true,
1078
+ background: false
1079
+ });
1080
+ const notices = pgNoticeOptions(deps.notice ?? ((line) => deps.progress(line.trimEnd())));
1081
+ const openFacts = () => postgres(toUrl, {
1082
+ ...notices,
1083
+ max: 1
1084
+ });
1085
+ const endFacts = (facts) => facts.end({ timeout: 5 }).catch(() => void 0);
1086
+ const src = postgres(fromUrl, {
1087
+ ...notices,
1088
+ max: 1,
1089
+ connection: {
1090
+ default_transaction_read_only: true,
1091
+ statement_timeout: 0,
1092
+ idle_in_transaction_session_timeout: 0,
1093
+ transaction_timeout: 0
1094
+ }
1095
+ });
1096
+ let target;
1097
+ try {
1098
+ let keptSeeds;
1099
+ let defaulted;
1100
+ let tables;
1101
+ if (args.verifyOnly) {
1102
+ const facts = openFacts();
1103
+ try {
1104
+ await assertSchema(src, args.fromSchema, "source");
1105
+ await assertSchema(facts, args.toSchema, "target");
1106
+ await assertDistinct(src, facts);
1107
+ await assertCopyDone(facts);
1108
+ } finally {
1109
+ await endFacts(facts);
1110
+ }
1111
+ target = await phase("prepare", boot);
1112
+ const state = await readCopyState(target);
1113
+ ({keptSeeds, defaulted, tables} = state);
1114
+ } else {
1115
+ const pre = await phase("preflight", async () => {
1116
+ const facts = openFacts();
1117
+ try {
1118
+ const own = await ownSession(facts);
1119
+ await assertSchema(src, args.fromSchema, "source");
1120
+ await assertSchema(facts, args.toSchema, "target");
1121
+ await assertDistinct(src, facts);
1122
+ const source = await inspectSource(src);
1123
+ source.otherSessions -= await sessionsOn(src, own);
1124
+ const target = await targetFacts(facts, env, diskPath);
1125
+ const pluginTables = await storeTables(pluginDir);
1126
+ return {
1127
+ source,
1128
+ ...preflight(source, target, {
1129
+ skipTables: args.skipTables,
1130
+ pluginTables,
1131
+ dryRun: args.dryRun
1132
+ })
1133
+ };
1134
+ } finally {
1135
+ await endFacts(facts);
1136
+ }
1137
+ });
1138
+ report.refusals.push(...pre.refusals);
1139
+ report.warnings.push(...pre.warnings);
1140
+ report.plan = planOf(pre.plan);
1141
+ if (report.refusals.length > 0) return finish(2);
1142
+ if (args.dryRun) {
1143
+ report.types = pre.source.types;
1144
+ return finish(0);
1145
+ }
1146
+ const copied = await phase("prepare-and-copy", () => copyStore(src, boot, pre.plan, {
1147
+ batchRows: args.batchRows,
1148
+ onProgress: (e) => deps.progress(` ${e.table}: ${e.rows} rows, ${e.bytes} bytes${e.done ? ", done" : ""}`)
1149
+ }));
1150
+ target = copied.target;
1151
+ report.tables = copied.tables;
1152
+ ({keptSeeds, defaulted} = copied);
1153
+ tables = pre.plan.tables.map((t) => t.name);
1154
+ }
1155
+ const booted = target;
1156
+ const indexFailures = args.skipIndexBuild ? [] : await phase("indexes", () => (deps.buildIndexes ?? buildDeferredIndexes)(booted.engine, booted.datasets));
1157
+ report.keptSeeds = keptSeeds.map((k) => `${k.namespace}/${k.type}/${k.id}`);
1158
+ report.defaulted = defaulted.map((d) => `${d.namespace}/${d.type}`);
1159
+ const tsql = booted.sql;
1160
+ await deps.beforeVerify?.(tsql);
1161
+ const verified = await phase("verify", () => verifyStore(src, tsql, {
1162
+ keptSeeds,
1163
+ defaulted,
1164
+ tables,
1165
+ fullChecksum: args.fullChecksum,
1166
+ sampleRows: 1e3,
1167
+ partitionBudget: parseEnv(targetEnv).partitionBudget,
1168
+ storageReport: async (r) => {
1169
+ const { warnings } = await booted.dataset.storageReport(r);
1170
+ const failed = [...indexFailures, ...await invalidIndexes(tsql)];
1171
+ if (!args.skipIndexBuild) return { warnings: [...warnings, ...failed] };
1172
+ report.pendingIndexes = warnings.filter((w) => PENDING_INDEX.test(w));
1173
+ return { warnings: [...warnings.filter((w) => !PENDING_INDEX.test(w)), ...failed] };
1174
+ }
1175
+ }));
1176
+ report.mismatches = verified.mismatches;
1177
+ if (!verified.ok) return finish(3);
1178
+ report.switchOver = `stop serve, set SUBSTRATE_DATABASE_URL to the value of ${args.toEnv}${args.toSchema !== null ? ` with search_path ${args.toSchema},public (options=-c search_path=${args.toSchema},public)` : ""}, then start serve. The source is untouched: pointing back at it is the rollback.`;
1179
+ return finish(0);
1180
+ } finally {
1181
+ await target?.close().catch(() => void 0);
1182
+ await src.end({ timeout: 5 }).catch(() => void 0);
1183
+ }
1184
+ }
1185
+ function planOf(plan) {
1186
+ return {
1187
+ tables: plan.tables.map((t) => ({
1188
+ name: t.name,
1189
+ bytes: t.bytes
1190
+ })),
1191
+ estimatedBytes: plan.estimatedBytes,
1192
+ skipped: plan.skipped
1193
+ };
1194
+ }
1195
+ /** The target schema's INVALID indexes, which a failed CREATE INDEX CONCURRENTLY leaves behind. */
1196
+ async function invalidIndexes(sql) {
1197
+ return (await sql`
1198
+ SELECT c.relname AS name, t.relname AS tbl
1199
+ FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid JOIN pg_class t ON t.oid = i.indrelid
1200
+ WHERE c.relnamespace = current_schema()::regnamespace AND NOT i.indisvalid
1201
+ ORDER BY c.relname`).map((r) => `index ${r.name} on ${r.tbl} is INVALID: rerun with --verify-only (without --skip-index-build), which rebuilds an engine index; drop or REINDEX any other INVALID index by hand`);
1202
+ }
1203
+ /** Refuses a named schema the connection did not land in: an unknown name on search_path falls through to public. */
1204
+ async function assertSchema(sql, schema, side) {
1205
+ const [r] = await sql`SELECT current_schema() AS s`;
1206
+ if (schema !== null && r?.s !== schema) throw new AdminCliError(`migrate-store: the ${side} has no schema ${schema}`, 2);
1207
+ }
1208
+ const storeId = async (sql) => {
1209
+ const [r] = await sql`
1210
+ SELECT concat_ws('/', (SELECT system_identifier FROM pg_control_system())::text,
1211
+ current_database(), current_schema()) AS id`;
1212
+ return r?.id;
1213
+ };
1214
+ /** Refuses a source and target that are one store: same cluster, database and schema. */
1215
+ async function assertDistinct(src, tgt) {
1216
+ if (await storeId(src) === await storeId(tgt)) throw new AdminCliError("migrate-store: the source and the target are the same store", 2);
1217
+ }
1218
+ /** Refuses `--verify-only` on a target with no finished migrate-store copy. */
1219
+ async function assertCopyDone(sql) {
1220
+ const [r] = await sql`
1221
+ SELECT to_regclass(quote_ident(current_schema()) || '.' || quote_ident(${MIGRATE_STORE_MARKER_TABLE}))::text AS marker`;
1222
+ if (r?.marker == null) throw new AdminCliError("migrate-store: the target is already verified, or not a migrate-store target (no marker)", 2);
1223
+ if ((await sql`SELECT 1 FROM ${sql(r.marker)} WHERE step = 'copy:done'`).length === 0) throw new AdminCliError("migrate-store: the target holds no finished migrate-store copy to verify (no in-progress marker with a completed copy)", 2);
1224
+ }
1225
+ async function ownSession(sql) {
1226
+ const [r] = await sql`
1227
+ SELECT pid, extract(epoch FROM backend_start)::text AS start
1228
+ FROM pg_stat_activity WHERE pid = pg_backend_pid()`;
1229
+ return r;
1230
+ }
1231
+ /** 1 when `s` is a backend on `sql`'s database, else 0: our own target connection when both share one. */
1232
+ async function sessionsOn(sql, s) {
1233
+ const [r] = await sql`
1234
+ SELECT count(*)::int AS n FROM pg_stat_activity
1235
+ WHERE datname = current_database() AND pid = ${s.pid}
1236
+ AND extract(epoch FROM backend_start)::text = ${s.start}`;
1237
+ return r?.n ?? 0;
1238
+ }
1239
+ async function targetFacts(sql, env, diskPath) {
1240
+ const [r] = await sql`
1241
+ SELECT current_setting('server_version_num')::int AS v, current_schema() AS schema,
1242
+ to_regclass(quote_ident(current_schema()) || '.rows') IS NOT NULL AS rows,
1243
+ to_regclass(quote_ident(current_schema()) || '.' || quote_ident(${MIGRATE_STORE_MARKER_TABLE})) IS NOT NULL AS marker,
1244
+ to_regclass(quote_ident(current_schema()) || '.embeddings') IS NOT NULL AS embeddings`;
1245
+ const facts = r;
1246
+ const empty = !facts.rows || (await sql`SELECT 1 FROM ${sql(facts.schema)}.rows LIMIT 1`).length === 0;
1247
+ const [dims] = facts.embeddings ? await sql`
1248
+ SELECT atttypmod AS d FROM pg_attribute
1249
+ WHERE attrelid = to_regclass(quote_ident(${facts.schema}) || '.embeddings')
1250
+ AND attname = 'embedding' AND NOT attisdropped` : [];
1251
+ const extensions = await sql`
1252
+ SELECT e.extname AS name, e.extversion AS version
1253
+ FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace
1254
+ WHERE n.nspname = ANY (current_schemas(true))`;
1255
+ let freeBytes = null;
1256
+ if (diskPath !== void 0 && diskPath.length > 0 && diskPath !== "off") {
1257
+ const s = await statfs(diskPath).catch((err) => {
1258
+ if (err.code !== "ENOENT") throw err;
1259
+ throw new AdminCliError(`migrate-store: SUBSTRATE_INDEX_DISK_PATH names a path that does not exist; set it to the target database volume mount, or to off`, 2);
1260
+ });
1261
+ freeBytes = s.bavail * s.bsize;
1262
+ }
1263
+ return {
1264
+ serverVersionNum: facts.v,
1265
+ empty,
1266
+ createdByUs: facts.marker,
1267
+ enforceUuidCheck: env.SUBSTRATE_ENFORCE_UUID_CHECK === "true",
1268
+ recallDims: dims !== void 0 && dims.d > 0 ? dims.d : null,
1269
+ extensions: Object.fromEntries(extensions.map((e) => [e.name, e.version])),
1270
+ freeBytes
1271
+ };
1272
+ }
1273
+ /** The loaded kernel plugins' `storeTables`, loaded as serve loads them but never composed. */
1274
+ async function storeTables(pluginDir) {
1275
+ if (pluginDir === null) return [];
1276
+ const { kernel } = await loadPluginsFromDir({
1277
+ pluginDir,
1278
+ kernelHostDeps: {},
1279
+ contractCheck: {
1280
+ hostVersion: BINARY_CONTRACT_VERSION,
1281
+ onViolation: refuseContractViolation
1282
+ }
1283
+ });
1284
+ return kernel.flatMap((p) => p.storeTables ?? []);
1285
+ }
1286
+ function formatMigrateStoreOutput(r, json) {
1287
+ if (json) return `${JSON.stringify(r)}\n`;
1288
+ const lines = [];
1289
+ const verdict = r.exitCode === 0 ? r.mode === "dry-run" ? "dry run: nothing written" : "copied and verified" : r.exitCode === 3 ? "VERIFICATION FAILED: the target keeps its in-progress marker, so serve will not boot it" : "REFUSED: nothing was written to the target";
1290
+ lines.push(`migrate-store (${r.mode}): ${verdict}`);
1291
+ for (const x of r.refusals) lines.push(` refused: ${x}`);
1292
+ for (const x of r.warnings) lines.push(` warning: ${x}`);
1293
+ if (r.types !== void 0) {
1294
+ lines.push("source types (live / deleted / bytes):");
1295
+ for (const t of r.types) lines.push(` ${t.namespace}/${t.type}: ${t.live} / ${t.deleted} / ${t.bytes}`);
1296
+ }
1297
+ if (r.plan !== void 0) {
1298
+ lines.push(`plan (estimated target need ${r.plan.estimatedBytes} bytes):`);
1299
+ for (const t of r.plan.tables) lines.push(` ${t.name}: ${t.bytes} bytes`);
1300
+ if (r.plan.skipped.length > 0) lines.push(` skipped: ${r.plan.skipped.join(", ")}`);
1301
+ }
1302
+ if (r.tables.length > 0) {
1303
+ lines.push("copied (rows / bytes / ms):");
1304
+ for (const t of r.tables) lines.push(` ${t.name}: ${t.rows} / ${t.bytes} / ${t.ms}`);
1305
+ }
1306
+ if (r.keptSeeds.length > 0) lines.push(`kept seeds: ${r.keptSeeds.join(", ")}`);
1307
+ if (r.defaulted.length > 0) lines.push(`in the DEFAULT partition: ${r.defaulted.join(", ")}`);
1308
+ if (r.pendingIndexes.length > 0) {
1309
+ lines.push(`${r.pendingIndexes.length} index build(s) left pending for serve (--skip-index-build; --json lists them all):`);
1310
+ for (const w of r.pendingIndexes.slice(0, 10)) lines.push(` ${w}`);
1311
+ }
1312
+ for (const m of r.mismatches) {
1313
+ const at = m.namespace !== void 0 ? ` ${m.namespace}/${m.type}` : "";
1314
+ lines.push(` mismatch [${m.check}]${at}: ${m.detail}`);
1315
+ }
1316
+ const phases = Object.entries(r.phases).map(([k, v]) => `${k} ${v}`);
1317
+ lines.push(`ms: ${[...phases, `total ${r.totalMs}`].join(", ")}`);
1318
+ if (r.switchOver !== null) lines.push(`switch over: ${r.switchOver}`);
1319
+ return `${lines.join("\n")}\n`;
1320
+ }
1321
+ /**
1322
+ * The CLI door: parse, run, print, exit code. Every string bound for stdout or
1323
+ * stderr passes one redactor, so no connection string reaches either.
1324
+ */
1325
+ async function migrateStoreCommand(tail, env, out, errOut, hooks = {}) {
1326
+ const vars = env;
1327
+ const names = /* @__PURE__ */ new Set([
1328
+ DEFAULT_FROM_ENV,
1329
+ DEFAULT_TO_ENV,
1330
+ "SUBSTRATE_DATABASE_URL"
1331
+ ]);
1332
+ for (let i = 0; i < tail.length - 1; i++) if (tail[i] === "--from-env" || tail[i] === "--to-env") names.add(tail[i + 1]);
1333
+ const redact = redactor([...names].flatMap((n) => secretsOf(vars[n])));
1334
+ const err = (s) => errOut(redact(s));
1335
+ const stdoutWrite = process.stdout.write;
1336
+ const stderrWrite = process.stderr.write;
1337
+ const realStderr = stderrWrite.bind(process.stderr);
1338
+ process.stdout.write = shim((s) => err(s));
1339
+ process.stderr.write = shim((s) => realStderr(redact(s)));
1340
+ let report;
1341
+ let json = false;
1342
+ try {
1343
+ const args = parseMigrateStoreArgs(tail);
1344
+ json = args.json;
1345
+ report = await runMigrateStore(args, env, {
1346
+ progress: (line) => err(`${line}\n`),
1347
+ ...hooks
1348
+ });
1349
+ } catch (e) {
1350
+ err(`${e instanceof Error ? e.message : String(e)}\n`);
1351
+ return e instanceof AdminCliError ? e.exitCode : 1;
1352
+ } finally {
1353
+ process.stdout.write = stdoutWrite;
1354
+ process.stderr.write = stderrWrite;
1355
+ }
1356
+ out(redact(formatMigrateStoreOutput(report, json)));
1357
+ return report.exitCode;
1358
+ }
1359
+ /** A `stream.write` stand-in that hands decoded text to `sink`, honouring `encoding` and `callback`. */
1360
+ function shim(sink) {
1361
+ return ((chunk, encoding, callback) => {
1362
+ const cb = typeof encoding === "function" ? encoding : callback;
1363
+ const enc = typeof encoding === "string" ? encoding : void 0;
1364
+ sink(typeof chunk === "string" ? enc === void 0 || enc === "utf8" || enc === "utf-8" ? chunk : Buffer.from(chunk, enc).toString("utf8") : Buffer.from(chunk).toString("utf8"));
1365
+ if (cb !== void 0) process.nextTick(cb, null);
1366
+ return true;
1367
+ });
1368
+ }
1369
+
1370
+ //#endregion
1371
+ //#region src/admin/commands/revoke.ts
1372
+ /**
1373
+ * `revoke` — soft-delete a Key by stamping `revokedAt`.
1374
+ *
1375
+ * Refuses the last active admin. `checkRevocable` is shared with the route so
1376
+ * both transports enforce the same floor.
1377
+ */
1378
+ async function runRevoke(kid, env, openDataset = openPgDataset) {
1379
+ if (kid === void 0 || kid.length === 0) throw argvError("revoke", "revoke requires a <kid> positional arg");
1380
+ const adminCapability = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : "admin";
1381
+ const { dataset, close } = await openDataset(env);
1382
+ try {
1383
+ return await dataset.withTransaction(async (tx) => {
1384
+ const existing = await readKeyById(tx, kid);
1385
+ const refusal = checkRevocable({
1386
+ kid,
1387
+ exists: existing !== null,
1388
+ existingRevokedAt: existing?.revokedAt,
1389
+ activeAdminKids: (await listActiveAdminKeys(tx, adminCapability)).map((a) => a.kid)
1390
+ });
1391
+ if (refusal !== null) throw new AdminCliError(refusal.message, REVOKE_EXIT_CODES[refusal.code]);
1392
+ const now = /* @__PURE__ */ new Date();
1393
+ const mergedRow = forUpdate({
1394
+ ...existing.row,
1395
+ revokedAt: now
1396
+ });
1397
+ await tx.write("Key", [mergedRow], ACTOR_HINT);
1398
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
1399
+ actorKid: CLI_ACTOR_KID,
1400
+ kind: "key_revoked",
1401
+ targetKid: kid,
1402
+ details: {
1403
+ revokedAt: now.toISOString(),
1404
+ cliSubcommand: "revoke"
1405
+ },
1406
+ now
1407
+ })], ACTOR_HINT);
1408
+ return {
1409
+ kid,
1410
+ revokedAt: now.toISOString()
1411
+ };
1412
+ });
1413
+ } finally {
1414
+ await close();
1415
+ }
1416
+ }
1417
+ function formatRevokeOutput(result) {
1418
+ return [
1419
+ `Key ${result.kid} revoked at ${result.revokedAt}`,
1420
+ "",
1421
+ RESTART_NOTE,
1422
+ ""
1423
+ ].join("\n");
1424
+ }
1425
+
1426
+ //#endregion
1427
+ //#region src/admin/commands/rotate.ts
1428
+ /**
1429
+ * `rotate` — mint a fresh keypair for an existing kid and retire the old row,
1430
+ * in one transaction.
1431
+ *
1432
+ * `--out` is required and must not already exist. An admin tool that silently
1433
+ * clobbers an operator's private key destroys the only copy of a credential.
1434
+ */
1435
+ function parseRotateArgs(argv) {
1436
+ try {
1437
+ return parseRotateArgsInner(argv);
1438
+ } catch (err) {
1439
+ if (err instanceof AdminCliError) throw argvError("rotate", err.message, err.exitCode);
1440
+ throw err;
1441
+ }
1442
+ }
1443
+ function parseRotateArgsInner(argv) {
1444
+ const rest = argv.slice(1);
1445
+ validateArgv("rotate", rest);
1446
+ let kid;
1447
+ let outPath;
1448
+ let wantsEncrypt = false;
1449
+ for (let i = 0; i < rest.length; i++) {
1450
+ const tok = rest[i];
1451
+ if (tok === void 0) continue;
1452
+ if (tok === "--out") {
1453
+ if (outPath !== void 0) throw new AdminCliError("rotate: --out specified more than once", 1);
1454
+ const val = rest[i + 1];
1455
+ if (val === void 0 || val.length === 0 || val.startsWith("--")) throw new AdminCliError("rotate: --out requires a path argument", 1);
1456
+ outPath = val;
1457
+ i += 1;
1458
+ } else if (tok === "--encrypt") {
1459
+ if (wantsEncrypt) throw new AdminCliError("rotate: --encrypt specified more than once", 1);
1460
+ wantsEncrypt = true;
1461
+ } else kid = tok;
1462
+ }
1463
+ if (kid === void 0 || kid.length === 0) throw new AdminCliError("rotate requires a <kid> positional arg", 1);
1464
+ if (outPath === void 0 || outPath.length === 0) throw new AdminCliError("rotate requires --out <path>", 1);
1465
+ return {
1466
+ kid,
1467
+ outPath,
1468
+ wantsEncrypt
1469
+ };
1470
+ }
1471
+ async function runRotate(kid, outPath, env, wantsEncrypt = false, openDataset = openPgDataset) {
1472
+ if (kid === void 0 || kid.length === 0) throw new AdminCliError("rotate requires a <kid> positional arg");
1473
+ if (outPath === void 0 || outPath.length === 0) throw new AdminCliError("rotate requires --out <path>");
1474
+ if (existsSync(outPath)) throw new AdminCliError(`--out path already exists: ${outPath} (move it aside and retry)`, 2);
1475
+ const { publicKeyPem, privateKeyPem, encrypted } = generateAdminKeypair(env, wantsEncrypt);
1476
+ try {
1477
+ mkdirSync(dirname(outPath), {
1478
+ recursive: true,
1479
+ mode: 448
1480
+ });
1481
+ writeFileSync(outPath, privateKeyPem, {
1482
+ mode: 384,
1483
+ flag: "wx"
1484
+ });
1485
+ } catch (err) {
1486
+ const msg = err instanceof Error ? err.message : String(err);
1487
+ throw new AdminCliError(`failed to write private key to '${outPath}': ${msg}. Nothing was changed.`, 5);
1488
+ }
1489
+ let committed = false;
1490
+ const { dataset, close } = await openDataset(env).catch((err) => {
1491
+ rmSync(outPath, { force: true });
1492
+ throw err;
1493
+ });
1494
+ try {
1495
+ const newKid = randomUUID();
1496
+ const shaFull = createHash("sha256").update(publicKeyPem).digest();
1497
+ const fingerprint = `sha256:${base64Url(shaFull).slice(0, 8)}`;
1498
+ const { name, namespaces, capabilities } = await dataset.withTransaction(async (tx) => {
1499
+ const existing = await readKeyById(tx, kid);
1500
+ if (existing === null) throw new AdminCliError(`no Key with kid ${kid}`, 3);
1501
+ if (existing.revokedAt != null) throw new AdminCliError(`cannot rotate revoked Key ${kid}`, 4);
1502
+ const preservedName = typeof existing.row.name === "string" ? existing.row.name : "";
1503
+ const preservedAlgorithm = typeof existing.row.algorithm === "string" ? existing.row.algorithm : "EdDSA";
1504
+ if (preservedAlgorithm !== "EdDSA") throw new AdminCliError(`cannot rotate Key with algorithm '${preservedAlgorithm}' — only EdDSA is currently supported by the CLI`, 5);
1505
+ const preservedNamespaces = typeof existing.row.namespaces === "string" ? existing.row.namespaces : "";
1506
+ const preservedCapabilities = typeof existing.row.capabilities === "string" ? existing.row.capabilities : "";
1507
+ const preservedKid = existing.row.kid;
1508
+ const now = /* @__PURE__ */ new Date();
1509
+ await tx.write("Key", [forUpdate({
1510
+ ...existing.row,
1511
+ revokedAt: now
1512
+ })], ACTOR_HINT);
1513
+ await tx.write("Key", [{
1514
+ id: newKid,
1515
+ kid: preservedKid,
1516
+ name: preservedName,
1517
+ algorithm: preservedAlgorithm,
1518
+ publicKey: publicKeyPem,
1519
+ namespaces: preservedNamespaces,
1520
+ capabilities: preservedCapabilities,
1521
+ revokedAt: null
1522
+ }], ACTOR_HINT);
1523
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
1524
+ actorKid: CLI_ACTOR_KID,
1525
+ kind: "key_rotated",
1526
+ targetKid: kid,
1527
+ details: {
1528
+ oldKid: kid,
1529
+ newKid,
1530
+ name: preservedName
1531
+ },
1532
+ now
1533
+ })], ACTOR_HINT);
1534
+ return {
1535
+ name: preservedName,
1536
+ namespaces: preservedNamespaces,
1537
+ capabilities: preservedCapabilities
1538
+ };
1539
+ });
1540
+ committed = true;
1541
+ return {
1542
+ oldKid: kid,
1543
+ newKid,
1544
+ fingerprint,
1545
+ privateKeyPath: outPath,
1546
+ name,
1547
+ namespaces,
1548
+ capabilities,
1549
+ encrypted
1550
+ };
1551
+ } finally {
1552
+ if (!committed) rmSync(outPath, { force: true });
1553
+ await close();
1554
+ }
1555
+ }
1556
+ function formatRotateOutput(result) {
1557
+ const encLabel = result.encrypted ? "encrypted: aes-256-cbc+pbes2" : "unencrypted";
1558
+ return [
1559
+ "substrate-admin rotate complete.",
1560
+ `old kid: ${result.oldKid}`,
1561
+ `new kid: ${result.newKid}`,
1562
+ `fingerprint: ${result.fingerprint}`,
1563
+ `private key: ${result.privateKeyPath} (mode 0600, ${encLabel})`,
1564
+ `namespaces: ${result.namespaces}`,
1565
+ `capabilities: ${result.capabilities}`,
1566
+ "",
1567
+ `Use the new private key to sign JWTs with kid=${result.newKid} to authenticate. The old key is revoked and no longer valid.`,
1568
+ "",
1569
+ RESTART_NOTE,
1570
+ ""
1571
+ ].join("\n");
1572
+ }
1573
+
1574
+ //#endregion
1575
+ //#region src/admin/commands/update.ts
1576
+ /**
1577
+ * `update` — change a live key's grant in place, leaving the keypair alone.
1578
+ *
1579
+ * An omitted flag leaves that field unchanged; `--ns` REPLACES rather than
1580
+ * merges. Widening authority needs `--widen`, narrowing does not, and the audit
1581
+ * event carries before AND after so a grant change is reconstructable from the
1582
+ * trail rather than from whoever remembers running it.
1583
+ */
1584
+ /**
1585
+ * Parse `update <kid> [--ns <csv>] [--caps <csv>] [--name <n>] [--widen]
1586
+ * [--allow-admin]`.
1587
+ *
1588
+ * Unlike `parseRegisterArgs`, an omitted flag means LEAVE UNCHANGED: the
1589
+ * defaulting `register` does at parse time (caps → read,mutate, name → kid)
1590
+ * is deliberately not repeated, so `update <kid> --name foo` cannot change
1591
+ * the grant.
1592
+ */
1593
+ function parseUpdateArgs(argv) {
1594
+ try {
1595
+ return parseUpdateArgsInner(argv);
1596
+ } catch (err) {
1597
+ if (err instanceof AdminCliError) throw argvError("update", err.message, err.exitCode);
1598
+ throw err;
1599
+ }
1600
+ }
1601
+ function parseUpdateArgsInner(argv) {
1602
+ const rest = argv.slice(1);
1603
+ validateArgv("update", rest);
1604
+ let kid;
1605
+ let name;
1606
+ let nsCsv;
1607
+ let capsCsv;
1608
+ let widen = false;
1609
+ let allowAdmin = false;
1610
+ let allowUnknownNs = false;
1611
+ let url = null;
1612
+ const takeValue = (flag, i) => {
1613
+ const val = rest[i + 1];
1614
+ if (val === void 0 || val.length === 0 || val.startsWith("--")) throw new AdminCliError(`update: ${flag} requires a value`, 1);
1615
+ return val;
1616
+ };
1617
+ for (let i = 0; i < rest.length; i++) {
1618
+ const tok = rest[i];
1619
+ if (tok === void 0) continue;
1620
+ if (tok === "--name") {
1621
+ if (name !== void 0) throw new AdminCliError("update: --name specified more than once", 1);
1622
+ name = takeValue("--name", i);
1623
+ i += 1;
1624
+ } else if (tok === "--ns") {
1625
+ if (nsCsv !== void 0) throw new AdminCliError("update: --ns specified more than once", 1);
1626
+ nsCsv = takeValue("--ns", i);
1627
+ i += 1;
1628
+ } else if (tok === "--caps") {
1629
+ if (capsCsv !== void 0) throw new AdminCliError("update: --caps specified more than once", 1);
1630
+ capsCsv = takeValue("--caps", i);
1631
+ i += 1;
1632
+ } else if (tok === "--url") {
1633
+ if (url === "") throw new AdminCliError("update: --direct and --url are mutually exclusive", 1);
1634
+ if (url !== null) throw new AdminCliError("update: --url specified more than once", 1);
1635
+ url = takeValue("--url", i);
1636
+ i += 1;
1637
+ } else if (tok === "--direct") {
1638
+ if (url !== null && url !== "") throw new AdminCliError("update: --direct and --url are mutually exclusive", 1);
1639
+ url = "";
1640
+ } else if (tok === "--allow-unknown-ns") allowUnknownNs = true;
1641
+ else if (tok === "--widen") {
1642
+ if (widen) throw new AdminCliError("update: --widen specified more than once", 1);
1643
+ widen = true;
1644
+ } else if (tok === "--allow-admin") {
1645
+ if (allowAdmin) throw new AdminCliError("update: --allow-admin specified more than once", 1);
1646
+ allowAdmin = true;
1647
+ } else kid = tok;
1648
+ }
1649
+ if (kid === void 0 || kid.length === 0) throw new AdminCliError("update requires a <kid> positional arg", 1);
1650
+ const splitCsv = (csv) => csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
1651
+ const namespaces = nsCsv === void 0 ? void 0 : splitCsv(nsCsv);
1652
+ if (namespaces !== void 0) {
1653
+ const nsError = grantEntryError(namespaces, ["read", "mutate"]);
1654
+ if (nsError !== null) throw new AdminCliError(`update: ${nsError} — e.g. --ns inventory:read,notes:read+mutate`, 1);
1655
+ }
1656
+ return {
1657
+ kid,
1658
+ name,
1659
+ namespaces,
1660
+ capabilities: capsCsv === void 0 ? void 0 : splitCsv(capsCsv),
1661
+ widen,
1662
+ allowAdmin,
1663
+ allowUnknownNs,
1664
+ url
1665
+ };
1666
+ }
1667
+ /**
1668
+ * NOTE on `--allow-unknown-ns`: the unhosted-namespace check is ROUTE-SIDE
1669
+ * only, because it needs the engine's federated schema. A `--direct` update
1670
+ * can still write a grant naming a namespace nobody hosts.
1671
+ */
1672
+ async function runUpdate(args, env, openDataset = openPgDataset) {
1673
+ if (args.name === void 0 && args.namespaces === void 0 && args.capabilities === void 0) throw new AdminCliError("update requires at least one of --ns, --caps or --name — there is nothing to change", 1);
1674
+ const adminCapability = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : "admin";
1675
+ const { dataset, close } = await openDataset(env);
1676
+ try {
1677
+ return await dataset.withTransaction(async (tx) => {
1678
+ const existing = await readKeyById(tx, args.kid);
1679
+ const prevNs = decodeList(existing?.row.namespaces);
1680
+ const prevCaps = decodeList(existing?.row.capabilities);
1681
+ const prevName = typeof existing?.row.name === "string" ? existing.row.name : "";
1682
+ const nextNs = args.namespaces ?? prevNs;
1683
+ const nextCaps = args.capabilities ?? prevCaps;
1684
+ const nextName = args.name ?? prevName;
1685
+ const refusal = checkUpdatable({
1686
+ kid: args.kid,
1687
+ exists: existing !== null,
1688
+ existingRevokedAt: existing?.revokedAt,
1689
+ prevNamespaces: prevNs,
1690
+ prevCapabilities: prevCaps,
1691
+ nextNamespaces: nextNs,
1692
+ nextCapabilities: nextCaps,
1693
+ activeAdminKids: (await listActiveAdminKeys(tx, adminCapability)).map((a) => a.kid),
1694
+ adminCapability,
1695
+ widen: args.widen === true,
1696
+ allowAdmin: args.allowAdmin === true
1697
+ });
1698
+ if (refusal !== null) {
1699
+ const suffix = refusal.code === "requires_widen" ? " Pass --widen to confirm it is deliberate. Narrowing a grant needs no flag." : refusal.code === "requires_allow_admin" ? "" : "";
1700
+ const message = refusal.code === "requires_allow_admin" ? "update: granting the 'admin' capability requires --allow-admin" : `${refusal.message}${suffix}`;
1701
+ throw new AdminCliError(message, UPDATE_EXIT_CODES[refusal.code]);
1702
+ }
1703
+ const nsGranted = newlyGranted(prevNs, nextNs);
1704
+ const capsGranted = newlyGranted(prevCaps, nextCaps);
1705
+ const before = {
1706
+ name: prevName,
1707
+ namespaces: encodeList(prevNs),
1708
+ capabilities: encodeList(prevCaps)
1709
+ };
1710
+ const after = {
1711
+ name: nextName,
1712
+ namespaces: encodeList(nextNs),
1713
+ capabilities: encodeList(nextCaps)
1714
+ };
1715
+ if (!(after.name !== before.name || after.namespaces !== before.namespaces || after.capabilities !== before.capabilities)) return {
1716
+ kid: args.kid,
1717
+ before,
1718
+ after,
1719
+ changed: false
1720
+ };
1721
+ const now = /* @__PURE__ */ new Date();
1722
+ await tx.write("Key", [forUpdate({
1723
+ ...existing.row,
1724
+ name: after.name,
1725
+ namespaces: after.namespaces,
1726
+ capabilities: after.capabilities
1727
+ })], ACTOR_HINT);
1728
+ await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
1729
+ actorKid: CLI_ACTOR_KID,
1730
+ kind: "key_authority_updated",
1731
+ targetKid: args.kid,
1732
+ details: {
1733
+ before,
1734
+ after,
1735
+ namespacesGranted: nsGranted,
1736
+ capabilitiesGranted: capsGranted,
1737
+ widened: nsGranted.length > 0 || capsGranted.length > 0,
1738
+ cliSubcommand: "update"
1739
+ },
1740
+ now
1741
+ })], ACTOR_HINT);
1742
+ return {
1743
+ kid: args.kid,
1744
+ before,
1745
+ after,
1746
+ changed: true
1747
+ };
1748
+ });
1749
+ } finally {
1750
+ await close();
1751
+ }
1752
+ }
1753
+ function formatUpdateOutput(result) {
1754
+ if (!result.changed) return [
1755
+ `substrate-admin update: no change — ${result.kid} already carries this authority.`,
1756
+ `name: ${result.before.name}`,
1757
+ ...grantLines("grant: ", result.before.namespaces, result.before.capabilities),
1758
+ ` (stored as: namespaces='${result.before.namespaces}' capabilities='${result.before.capabilities}')`,
1759
+ "",
1760
+ "Nothing was written and no audit row was emitted.",
1761
+ ""
1762
+ ].join("\n");
1763
+ const row = (label, b, a) => b === a ? `${label}${b === "" ? "(empty)" : b} (unchanged)` : `${label}${b} -> ${a}`;
1764
+ const beforeGrant = grantLines("grant before: ", result.before.namespaces, result.before.capabilities);
1765
+ const afterGrant = grantLines(" after: ", result.after.namespaces, result.after.capabilities);
1766
+ return [
1767
+ "substrate-admin update complete.",
1768
+ `kid: ${result.kid}`,
1769
+ row("name: ", result.before.name, result.after.name),
1770
+ ...beforeGrant,
1771
+ ...afterGrant,
1772
+ ` (stored as: namespaces='${result.after.namespaces}' capabilities='${result.after.capabilities}')`,
1773
+ "",
1774
+ RESTART_NOTE,
1775
+ ""
1776
+ ].join("\n");
1777
+ }
1778
+
1779
+ //#endregion
1780
+ //#region src/admin/main.ts
1781
+ /**
1782
+ * Argv -> subcommand dispatch.
1783
+ *
1784
+ * Every case here is thin on purpose: parse, resolve the target, call the
1785
+ * command module, format. The logic lives in `./commands/`, so this file stays
1786
+ * readable as the map of what the CLI can do.
1787
+ */
1788
+ /**
1789
+ * CLI entry point. Parses `process.argv`, dispatches to the requested
1790
+ * sub-command, and writes human-readable output. Returns the exit code so the
1791
+ * top-level runner can call `process.exit` once.
1792
+ */
1793
+ async function main(argv, env, out, errOut, openDataset = openPgDataset, prompt = {
1794
+ ask: async () => null,
1795
+ interactive: false
1796
+ }) {
1797
+ const command = argv[0];
1798
+ if (command === void 0) {
1799
+ errOut(`${USAGE}\n`);
1800
+ return 1;
1801
+ }
1802
+ if (command === "--version" || command === "-v" || command === "version") {
1803
+ out(`${version}\n`);
1804
+ return 0;
1805
+ }
1806
+ if (command === "help" || argv.some((a) => a === "--help" || a === "-h")) {
1807
+ out(`${USAGE}\n`);
1808
+ return 0;
1809
+ }
1810
+ try {
1811
+ if (ARGV_SPEC[command] === void 0) {
1812
+ errOut(`unknown command: ${command}\n${USAGE}\n`);
1813
+ return 1;
1814
+ }
1815
+ if (command !== "migrate-store") validateArgv(command, argv.slice(1));
1816
+ switch (command) {
1817
+ case "bootstrap": {
1818
+ const parsed = parseBootstrapArgs(argv);
1819
+ const result = await runBootstrap(env, parsed.wantsEncrypt);
1820
+ out(formatBootstrapOutput(result));
1821
+ return 0;
1822
+ }
1823
+ case "doctor": {
1824
+ const report = await doctorCommand(argv.slice(1), env);
1825
+ out(formatDoctorReport(report));
1826
+ return report.exitCode;
1827
+ }
1828
+ case "onboard": return onboardCommand(argv.slice(1), env, {
1829
+ out,
1830
+ ask: prompt.ask
1831
+ }, prompt.interactive);
1832
+ case "list": {
1833
+ const args = parseListArgs(argv.slice(1));
1834
+ if (args.url !== void 0) {
1835
+ const remote = await runKeyListViaRoute(args.url, env);
1836
+ out(formatRemoteListOutput(remote, args.url));
1837
+ return 0;
1838
+ }
1839
+ const rows = await runList(env, openDataset);
1840
+ out(formatListOutput(rows));
1841
+ return 0;
1842
+ }
1843
+ case "revoke": {
1844
+ const rest = argv.slice(1);
1845
+ let kid;
1846
+ let url;
1847
+ let direct = false;
1848
+ for (let i = 0; i < rest.length; i++) {
1849
+ const tok = rest[i];
1850
+ if (tok === void 0) continue;
1851
+ if (tok === "--url") {
1852
+ if (url !== void 0) throw argvError("revoke", "revoke: --url specified more than once", 1);
1853
+ url = rest[i + 1] ?? "";
1854
+ i += 1;
1855
+ continue;
1856
+ }
1857
+ if (tok === "--direct") {
1858
+ direct = true;
1859
+ continue;
1860
+ }
1861
+ kid = tok;
1862
+ }
1863
+ if (kid === void 0 || kid.length === 0) {
1864
+ errOut(`revoke requires a <kid> positional arg\n${USAGE}\n`);
1865
+ return 1;
1866
+ }
1867
+ if (direct && url !== void 0) throw argvError("revoke", "revoke: --direct and --url are mutually exclusive", 1);
1868
+ const target = resolveAdminTarget(direct ? "" : url ?? null, env);
1869
+ errOut(`${describeAdminTarget("revoke", target)}\n`);
1870
+ if (target.kind === "route") {
1871
+ const payload = await runKeyPatchViaRoute({
1872
+ kid,
1873
+ revoke: true
1874
+ }, target.baseUrl, env, REVOKE_EXIT_CODES);
1875
+ out(`Key ${String(payload.kid)} revoked at ${String(payload.revokedAt)} — the running server saw it.
1876
+ `);
1877
+ return 0;
1878
+ }
1879
+ const result = await runRevoke(kid, env, openDataset);
1880
+ out(formatRevokeOutput(result));
1881
+ return 0;
1882
+ }
1883
+ case "rotate": {
1884
+ const parsed = parseRotateArgs(argv);
1885
+ const result = await runRotate(parsed.kid, parsed.outPath, env, parsed.wantsEncrypt, openDataset);
1886
+ out(formatRotateOutput(result));
1887
+ return 0;
1888
+ }
1889
+ case "register": {
1890
+ const parsed = parseRegisterArgs(argv);
1891
+ const target = resolveAdminTarget(parsed.url, env);
1892
+ errOut(`${describeAdminTarget("register", target)}\n`);
1893
+ const result = target.kind === "route" ? await runRegisterViaRoute(parsed, target.baseUrl, env) : await runRegister(parsed, env, openDataset);
1894
+ out(formatRegisterOutput(result));
1895
+ return 0;
1896
+ }
1897
+ case "update": {
1898
+ const parsed = parseUpdateArgs(argv);
1899
+ const target = resolveAdminTarget(parsed.url, env);
1900
+ errOut(`${describeAdminTarget("update", target)}\n`);
1901
+ if (target.kind === "route") {
1902
+ const payload = await runKeyPatchViaRoute({
1903
+ kid: parsed.kid,
1904
+ ...parsed.name !== void 0 ? { name: parsed.name } : {},
1905
+ ...parsed.namespaces !== void 0 ? { namespaces: parsed.namespaces } : {},
1906
+ ...parsed.capabilities !== void 0 ? { capabilities: parsed.capabilities } : {},
1907
+ widen: parsed.widen === true,
1908
+ allowAdmin: parsed.allowAdmin === true,
1909
+ allowUnknownNs: parsed.allowUnknownNs
1910
+ }, target.baseUrl, env, UPDATE_EXIT_CODES);
1911
+ out(`Key ${String(payload.kid)} updated via the route — the running server saw it.\n`);
1912
+ return 0;
1913
+ }
1914
+ const result = await runUpdate(parsed, env, openDataset);
1915
+ out(formatUpdateOutput(result));
1916
+ return 0;
1917
+ }
1918
+ case "migrate-store": return migrateStoreCommand(argv.slice(1), env, out, errOut);
1919
+ default:
1920
+ errOut(`unknown command: ${command}\n${USAGE}\n`);
1921
+ return 1;
1922
+ }
1923
+ } catch (err) {
1924
+ const exitCode = err instanceof BootstrapError || err instanceof AdminCliError ? err.exitCode : 1;
1925
+ errOut(`${err instanceof Error ? err.message : String(err)}\n`);
1926
+ return exitCode;
1927
+ }
1928
+ }
1929
+
1930
+ //#endregion
1931
+ //#region src/admin/stdin-ask.ts
1932
+ /**
1933
+ * The line reader behind an interactive `substrate-admin onboard`.
1934
+ *
1935
+ * - End of input (Ctrl-D, a closed pipe) resolves the open question, and every later
1936
+ * one, with null — the loop turns that into a quit with its summary.
1937
+ * - Ctrl-C at a prompt does the same. Ctrl-C with no prompt open (an action or a fetch in
1938
+ * flight) calls `onInterrupt`, because no prompt will come back to notice a close.
1939
+ * - `terminal` is set from the INPUT, so redirecting stderr cannot turn Ctrl-C back into
1940
+ * a process-killing SIGINT.
1941
+ * - One pending resolver and one permanent close listener, so nothing accumulates per
1942
+ * question.
1943
+ */
1944
+ function createAsk(streams) {
1945
+ const rl = createInterface({
1946
+ input: streams.input,
1947
+ output: streams.output,
1948
+ terminal: streams.terminal
1949
+ });
1950
+ let closed = false;
1951
+ let pending = null;
1952
+ const settle = (line) => {
1953
+ const resolve = pending;
1954
+ pending = null;
1955
+ resolve?.(line);
1956
+ };
1957
+ rl.on("close", () => {
1958
+ closed = true;
1959
+ settle(null);
1960
+ });
1961
+ rl.on("SIGINT", () => {
1962
+ if (pending !== null) rl.close();
1963
+ else streams.onInterrupt();
1964
+ });
1965
+ return (prompt) => {
1966
+ if (closed) return Promise.resolve(null);
1967
+ return new Promise((resolve) => {
1968
+ pending = resolve;
1969
+ rl.question(prompt, (line) => settle(line));
1970
+ });
1971
+ };
1972
+ }
1973
+
1974
+ //#endregion
1975
+ //#region src/admin/run.ts
1976
+ /** Runs `substrate-admin` on this process's argv, then exits with its code. */
1977
+ function runAdminCli() {
1978
+ const interactive = process.stdin.isTTY === true && process.argv[2] === "onboard";
1979
+ main(process.argv.slice(2), process.env, (s) => process.stdout.write(s), (s) => process.stderr.write(s), openPgDataset, interactive ? {
1980
+ ask: createAsk({
1981
+ input: process.stdin,
1982
+ output: process.stderr,
1983
+ terminal: true,
1984
+ onInterrupt: () => {
1985
+ process.stderr.write("\ninterrupted.\n");
1986
+ process.exit(130);
1987
+ }
1988
+ }),
1989
+ interactive: true
1990
+ } : {
1991
+ ask: async () => null,
1992
+ interactive: false
1993
+ }).then((exitCode) => process.exit(exitCode));
1994
+ }
1995
+
1996
+ //#endregion
1997
+ export { runAdminCli };