@mistriwork/engine 1.0.0-rc.15 → 1.0.0-rc.17

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 (58) hide show
  1. package/README.md +5 -0
  2. package/dist/host.d.ts +46 -0
  3. package/dist/host.js +51 -0
  4. package/dist/server/cli/startup.js +7 -2
  5. package/dist/server/cli/usage.d.ts +2 -0
  6. package/dist/server/cli/usage.js +12 -1
  7. package/dist/server/clientHttp.js +20 -3
  8. package/dist/server/config/profile.d.ts +10 -3
  9. package/dist/server/config/profile.js +28 -4
  10. package/dist/server/connections.js +9 -0
  11. package/dist/server/http/baselineHeaders.d.ts +13 -3
  12. package/dist/server/http/baselineHeaders.js +6 -0
  13. package/dist/server/http/exportRoute.d.ts +74 -0
  14. package/dist/server/http/exportRoute.js +206 -169
  15. package/dist/server/http/frontDoor.d.ts +41 -0
  16. package/dist/server/http/frontDoor.js +36 -0
  17. package/dist/server/http/recordCompose.d.ts +3 -0
  18. package/dist/server/http/recordCompose.js +1 -0
  19. package/dist/server/http/reply.js +6 -0
  20. package/dist/server/http/serverCore.d.ts +2 -2
  21. package/dist/server/http/serverCore.js +16 -32
  22. package/dist/server/journal.d.ts +35 -6
  23. package/dist/server/journal.js +79 -8
  24. package/dist/server/journalStore.d.ts +37 -0
  25. package/dist/server/journalStore.js +352 -0
  26. package/dist/server/migrate/cli.js +8 -1
  27. package/dist/server/migrate/target.d.ts +8 -0
  28. package/dist/server/migrate/target.js +15 -0
  29. package/dist/server/seed/seed.js +46 -11
  30. package/dist/shared/appCards.d.ts +4 -0
  31. package/dist/shared/appCards.js +5 -0
  32. package/dist/shared/appListColumns.d.ts +7 -0
  33. package/dist/shared/appListColumns.js +13 -0
  34. package/dist/shared/breakdown.js +8 -2
  35. package/dist/shared/computed.d.ts +16 -2
  36. package/dist/shared/computed.js +23 -4
  37. package/dist/shared/computedValue.js +23 -0
  38. package/dist/shared/listQuestion.js +2 -2
  39. package/dist/shared/mentionLookup.js +3 -1
  40. package/dist/shared/page.js +23 -5
  41. package/dist/shared/pageAnatomy.js +2 -0
  42. package/dist/shared/pageConfig.d.ts +1 -1
  43. package/dist/shared/pageConfig.js +68 -18
  44. package/dist/shared/pageModel.d.ts +42 -5
  45. package/dist/shared/pagePaths.js +4 -1
  46. package/dist/shared/pagePlans.d.ts +2 -2
  47. package/dist/shared/pagePlans.js +3 -3
  48. package/dist/shared/recordLabel.d.ts +12 -3
  49. package/dist/shared/recordLabel.js +39 -18
  50. package/dist/shared/recordReads.d.ts +6 -30
  51. package/dist/shared/recordReads.js +32 -2
  52. package/dist/shared/rollups.d.ts +4 -4
  53. package/dist/shared/rollups.js +1 -1
  54. package/dist/shared/schema.d.ts +7 -0
  55. package/dist/shared/schema.js +17 -0
  56. package/dist/shared/servedApp.d.ts +1 -1
  57. package/dist/shared/viewLabels.js +22 -17
  58. package/package.json +5 -2
@@ -0,0 +1,352 @@
1
+ /**
2
+ * The write journal's store: where a connection's Undo history is kept when
3
+ * the database holds it, so a restart does not forget the writes it could
4
+ * still put back (journal.ts).
5
+ *
6
+ * The store is opt-in, like every reserved store: provisioned by an explicit
7
+ * step (`mistri migrate stores`, `provisionStores({ only: ['undo-journal'] })`,
8
+ * or the provisioning functions here for a host that has no App framework),
9
+ * never by opening a connection. A writable connection whose database holds
10
+ * this build's layout keeps its journal there; one that holds none keeps it in
11
+ * memory, as before, and one that holds another layout keeps it in memory and
12
+ * says why once.
13
+ *
14
+ * It sits in the business database, beside the rows it describes, under the
15
+ * reserved prefix: the catalog never lists it, and a copy of the database
16
+ * carries the history that belongs to it. What is kept is what memory holds —
17
+ * the entry the hidden-column wrapper already stripped — so a hidden value is
18
+ * no more in the store than it was in the journal.
19
+ *
20
+ * Retention is the journal's own depth (the newest `entries` per connection)
21
+ * and an age (`days`): an Undo a week later is an overwrite more often than
22
+ * not, and the revert's check-before-write is the only thing that would stop
23
+ * it. An entry too large to keep is kept as a barrier instead, which is what
24
+ * it is after a restart: a write whose inverse is gone, so no older Undo is
25
+ * offered past it.
26
+ */
27
+ import { statSync } from 'node:fs';
28
+ import { DatabaseSync } from 'node:sqlite';
29
+ import { Refusal } from '../adapters/adapter.js';
30
+ import { layoutRefusal, postgresLayoutVersion, sqliteLayoutVersion } from '../adapters/layoutRefusal.js';
31
+ import { withPostgresMaintenanceTransaction } from '../adapters/postgresMaintenance.js';
32
+ import { storeHostOf, writeViewOf } from '../adapters/storeHost.js';
33
+ import { runtimeName, runtimeSchema, runtimeTable } from '../shared/runtimeTables.js';
34
+ import { attachJournalStore } from './journal.js';
35
+ const WRITE_JOURNAL_VERSION = 1;
36
+ /** The reserved prefix of its tables (`mistri.undo_*` on PostgreSQL). */
37
+ const WRITE_JOURNAL_PREFIX = '__mistri_undo_';
38
+ const META = '__mistri_undo_meta';
39
+ const ENTRY = '__mistri_undo_entry';
40
+ /** How much is kept: the journal's depth per connection, a week, and an entry of at most 4 MiB. */
41
+ export const WRITE_JOURNAL_RETENTION = Object.freeze({ entries: 50, days: 7, bytes: 4 * 1024 * 1024 });
42
+ const DAY_MS = 86_400_000;
43
+ /** Why the store cannot be used: an unprovisioned database is not this; a layout that is not this build's is. */
44
+ class WriteJournalUnavailable extends Refusal {
45
+ constructor(message = 'The write journal store is missing or is not the layout this version expects.') {
46
+ super(message);
47
+ this.name = 'WriteJournalUnavailable';
48
+ }
49
+ }
50
+ /* ---------- SQLite ---------- */
51
+ const sqliteDefinitions = new Map([
52
+ [
53
+ META,
54
+ `CREATE TABLE "${META}" (
55
+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
56
+ version INTEGER NOT NULL CHECK (version = ${WRITE_JOURNAL_VERSION})
57
+ )`,
58
+ ],
59
+ [
60
+ ENTRY,
61
+ `CREATE TABLE "${ENTRY}" (
62
+ connection TEXT COLLATE BINARY NOT NULL,
63
+ id INTEGER NOT NULL,
64
+ at INTEGER NOT NULL,
65
+ entry_json TEXT NOT NULL CHECK (json_valid(entry_json)),
66
+ PRIMARY KEY (connection, id)
67
+ )`,
68
+ ],
69
+ ]);
70
+ const underPrefix = `substr(name, 1, ?) = ? COLLATE NOCASE OR substr(tbl_name, 1, ?) = ? COLLATE NOCASE`;
71
+ const prefixArgs = [WRITE_JOURNAL_PREFIX.length, WRITE_JOURNAL_PREFIX, WRITE_JOURNAL_PREFIX.length, WRITE_JOURNAL_PREFIX];
72
+ const sqliteCatalog = (db) => db
73
+ .prepare(`SELECT type, name, tbl_name, sql FROM main.sqlite_schema WHERE ${underPrefix}`)
74
+ .all(...prefixArgs);
75
+ /** Exactly this version's two tables and their key indexes, nothing else under the prefix, and its version row. */
76
+ export function sqliteWriteJournalReady(db) {
77
+ try {
78
+ if (db.prepare(`SELECT 1 FROM temp.sqlite_schema WHERE ${underPrefix} LIMIT 1`).get(...prefixArgs))
79
+ return false;
80
+ const entries = sqliteCatalog(db);
81
+ const tables = entries.filter((entry) => entry.type === 'table');
82
+ if (tables.length !== sqliteDefinitions.size ||
83
+ tables.some((entry) => sqliteDefinitions.get(entry.name) !== entry.sql) ||
84
+ entries.some((entry) => entry.type !== 'table' && !(entry.type === 'index' && entry.sql === null && sqliteDefinitions.has(entry.tbl_name))))
85
+ return false;
86
+ const rows = db.prepare(`SELECT singleton, version FROM main."${META}"`).all();
87
+ return rows.length === 1 && rows[0].singleton === 1 && rows[0].version === WRITE_JOURNAL_VERSION;
88
+ }
89
+ catch {
90
+ return false;
91
+ }
92
+ }
93
+ const inMain = (ddl) => ddl.replace('CREATE TABLE ', 'CREATE TABLE main.');
94
+ /**
95
+ * Explicit maintenance, never run when a connection opens: a file without the
96
+ * store gets this version; the same layout again changes nothing; anything
97
+ * else under the prefix is refused unchanged.
98
+ */
99
+ export function provisionSqliteWriteJournal(existingPath) {
100
+ if (!statSync(existingPath).isFile())
101
+ throw new Refusal('Write journal provisioning requires an existing SQLite file.');
102
+ const db = new DatabaseSync(existingPath);
103
+ try {
104
+ db.exec('PRAGMA busy_timeout = 5000');
105
+ db.exec('BEGIN IMMEDIATE');
106
+ try {
107
+ let provisioned = false;
108
+ if (sqliteCatalog(db).length === 0) {
109
+ for (const ddl of sqliteDefinitions.values())
110
+ db.exec(inMain(ddl));
111
+ db.prepare(`INSERT INTO main."${META}" (singleton, version) VALUES (1, ?)`).run(WRITE_JOURNAL_VERSION);
112
+ provisioned = true;
113
+ }
114
+ if (!sqliteWriteJournalReady(db))
115
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', sqliteLayoutVersion(db, META), WRITE_JOURNAL_VERSION));
116
+ db.exec('COMMIT');
117
+ return { version: WRITE_JOURNAL_VERSION, provisioned };
118
+ }
119
+ catch (error) {
120
+ try {
121
+ db.exec('ROLLBACK');
122
+ }
123
+ catch {
124
+ /* Preserve the provisioning failure. */
125
+ }
126
+ throw error;
127
+ }
128
+ }
129
+ finally {
130
+ db.close();
131
+ }
132
+ }
133
+ /* ---------- PostgreSQL ---------- */
134
+ const pgMeta = runtimeTable('postgres', META);
135
+ const pgEntry = runtimeTable('postgres', ENTRY);
136
+ const pgPrefix = runtimeName('postgres', WRITE_JOURNAL_PREFIX.slice(0, -1)) + '_';
137
+ const pgDefinitions = [
138
+ `CREATE TABLE ${pgMeta} (
139
+ singleton integer PRIMARY KEY CHECK (singleton = 1),
140
+ version integer NOT NULL CHECK (version = ${WRITE_JOURNAL_VERSION})
141
+ )`,
142
+ `CREATE TABLE ${pgEntry} (
143
+ connection text COLLATE "C" NOT NULL,
144
+ id bigint NOT NULL,
145
+ at bigint NOT NULL,
146
+ entry jsonb NOT NULL,
147
+ PRIMARY KEY (connection, id)
148
+ )`,
149
+ ];
150
+ /* What the DDL above reads back as, pinned so the attestation is of this layout and not of whatever is there. */
151
+ const PG_LAYOUT = JSON.stringify([
152
+ {
153
+ name: runtimeName('postgres', ENTRY),
154
+ kind: 'r',
155
+ columns: ['connection text C t', 'id bigint - t', 'at bigint - t', 'entry jsonb - t'],
156
+ constraints: ['PRIMARY KEY (connection, id)'],
157
+ },
158
+ {
159
+ name: `${runtimeName('postgres', ENTRY)}_pkey`,
160
+ kind: 'i',
161
+ columns: ['connection text C f', 'id bigint - f'],
162
+ constraints: [],
163
+ },
164
+ {
165
+ name: runtimeName('postgres', META),
166
+ kind: 'r',
167
+ columns: ['singleton integer - t', 'version integer - t'],
168
+ constraints: ['CHECK ((singleton = 1))', `CHECK ((version = ${WRITE_JOURNAL_VERSION}))`, 'PRIMARY KEY (singleton)'],
169
+ },
170
+ {
171
+ name: `${runtimeName('postgres', META)}_pkey`,
172
+ kind: 'i',
173
+ columns: ['singleton integer - f'],
174
+ constraints: [],
175
+ },
176
+ ]);
177
+ /** Every relation under the prefix in the runtime schema, with its columns and constraints, in a fixed order; triggers, rules and row security disqualify it. */
178
+ async function pgRelations(client) {
179
+ const rows = (await client.query(`SELECT c.relname AS name, c.relkind::text AS kind,
180
+ c.relrowsecurity OR c.relhastriggers OR c.relhasrules AS guarded,
181
+ coalesce((SELECT json_agg(a.attname || ' ' || format_type(a.atttypid, a.atttypmod) || ' ' ||
182
+ coalesce((SELECT co.collname FROM pg_collation co WHERE co.oid = a.attcollation AND a.attcollation <> 0
183
+ AND a.attcollation <> (SELECT t.typcollation FROM pg_type t WHERE t.oid = a.atttypid)), '-') || ' ' ||
184
+ CASE WHEN a.attnotnull THEN 't' ELSE 'f' END ORDER BY a.attnum)
185
+ FROM pg_attribute a WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped), '[]') AS columns,
186
+ coalesce((SELECT json_agg(pg_get_constraintdef(k.oid) ORDER BY pg_get_constraintdef(k.oid) COLLATE "C")
187
+ FROM pg_constraint k WHERE k.conrelid = c.oid), '[]') AS constraints,
188
+ (SELECT count(*) FROM pg_attrdef d WHERE d.adrelid = c.oid)::int AS defaults
189
+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
190
+ WHERE n.nspname = $1 AND substr(c.relname, 1, $2) = $3
191
+ ORDER BY c.relname COLLATE "C"`, [runtimeSchema('postgres'), pgPrefix.length, pgPrefix])).rows;
192
+ if (rows.some((row) => row.guarded || row.defaults))
193
+ return { text: '', count: rows.length };
194
+ return {
195
+ text: JSON.stringify(rows.map(({ name, kind, columns, constraints }) => ({ name, kind, columns, constraints }))),
196
+ count: rows.length,
197
+ };
198
+ }
199
+ /** Whether the reserved relations are exactly this version's layout with its version row. */
200
+ export async function postgresWriteJournalReady(client) {
201
+ try {
202
+ if ((await pgRelations(client)).text !== PG_LAYOUT)
203
+ return false;
204
+ const rows = (await client.query(`SELECT singleton, version FROM ${pgMeta}`)).rows;
205
+ return rows.length === 1 && rows[0].singleton === 1 && rows[0].version === WRITE_JOURNAL_VERSION;
206
+ }
207
+ catch {
208
+ return false;
209
+ }
210
+ }
211
+ /** Explicit maintenance, under the shared migration lock: creates this version
212
+ * where no store exists, changes nothing where it does, refuses anything else. */
213
+ export async function provisionPostgresWriteJournal(url) {
214
+ if (typeof url !== 'string' || !/^postgres(ql)?:\/\//i.test(url))
215
+ throw new Refusal('Write journal provisioning requires a postgres:// URL.');
216
+ return withPostgresMaintenanceTransaction(url, async (client) => {
217
+ let provisioned = false;
218
+ if (!(await pgRelations(client)).count) {
219
+ for (const ddl of pgDefinitions)
220
+ await client.query(ddl);
221
+ await client.query(`INSERT INTO ${pgMeta} (singleton, version) VALUES (1, $1)`, [WRITE_JOURNAL_VERSION]);
222
+ provisioned = true;
223
+ }
224
+ if (!(await postgresWriteJournalReady(client)))
225
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', await postgresLayoutVersion(client, pgMeta), WRITE_JOURNAL_VERSION));
226
+ return { version: WRITE_JOURNAL_VERSION, provisioned };
227
+ });
228
+ }
229
+ /* ---------- what is kept ---------- */
230
+ /** The stored form: the entry without the columns that say where and when it is. */
231
+ function stored(entry) {
232
+ const { id: _id, connection: _connection, at: _at, ...rest } = entry;
233
+ const json = JSON.stringify(rest);
234
+ if (Buffer.byteLength(json) <= WRITE_JOURNAL_RETENTION.bytes)
235
+ return json;
236
+ // Kept as what it is after a restart: a write with no inverse left, which blocks every older Undo.
237
+ const { steps, ...plain } = rest;
238
+ return JSON.stringify({
239
+ ...plain,
240
+ revertible: false,
241
+ blocksUndo: true,
242
+ reason: 'This write was too large to keep its Undo across a restart.',
243
+ steps: steps.length ? [{ table: steps[0].table }] : [],
244
+ });
245
+ }
246
+ function revived(connection, id, at, json) {
247
+ const body = (typeof json === 'string' ? JSON.parse(json) : json);
248
+ return { ...body, id: Number(id), connection, at: new Date(Number(at)).toISOString() };
249
+ }
250
+ const atOf = (entry) => {
251
+ const at = Date.parse(entry.at);
252
+ return Number.isFinite(at) ? at : Date.now();
253
+ };
254
+ const oldest = () => Date.now() - WRITE_JOURNAL_RETENTION.days * DAY_MS;
255
+ function sqliteStore(host) {
256
+ const prune = (db, connection) => db
257
+ .prepare(`DELETE FROM main."${ENTRY}" WHERE connection = ? AND (at < ? OR id NOT IN
258
+ (SELECT id FROM main."${ENTRY}" WHERE connection = ? ORDER BY id DESC LIMIT ?))`)
259
+ .run(connection, oldest(), connection, WRITE_JOURNAL_RETENTION.entries);
260
+ return {
261
+ load: (connection) => host.queueWrite((db) => {
262
+ prune(db, connection);
263
+ return db.prepare(`SELECT id, at, entry_json FROM main."${ENTRY}" WHERE connection = ? ORDER BY id`).all(connection).map((row) => revived(connection, row.id, row.at, row.entry_json));
264
+ }),
265
+ append: (entry) => host.queueWrite((db) => {
266
+ db.prepare(`INSERT INTO main."${ENTRY}" (connection, id, at, entry_json) VALUES (?, ?, ?, ?)`).run(entry.connection, entry.id, atOf(entry), stored(entry));
267
+ prune(db, entry.connection);
268
+ }),
269
+ update: (entry) => host.queueWrite((db) => {
270
+ db.prepare(`UPDATE main."${ENTRY}" SET entry_json = ? WHERE connection = ? AND id = ?`).run(stored(entry), entry.connection, entry.id);
271
+ }),
272
+ remove: (connection, id) => host.queueWrite((db) => {
273
+ db.prepare(`DELETE FROM main."${ENTRY}" WHERE connection = ? AND id = ?`).run(connection, id);
274
+ }),
275
+ };
276
+ }
277
+ function postgresStore(host) {
278
+ const prune = (client, connection) => client.query(`DELETE FROM ${pgEntry} WHERE connection = $1 AND (at < $2 OR id NOT IN
279
+ (SELECT id FROM ${pgEntry} WHERE connection = $1 ORDER BY id DESC LIMIT $3))`, [connection, oldest(), WRITE_JOURNAL_RETENTION.entries]);
280
+ return {
281
+ load: (connection) => host.withWriteClient(async (client) => {
282
+ await prune(client, connection);
283
+ const rows = (await client.query(`SELECT id, at, entry FROM ${pgEntry} WHERE connection = $1 ORDER BY id`, [connection]))
284
+ .rows;
285
+ return rows.map((row) => revived(connection, row.id, row.at, row.entry));
286
+ }),
287
+ append: (entry) => host.withWriteClient(async (client) => {
288
+ await client.query(`INSERT INTO ${pgEntry} (connection, id, at, entry) VALUES ($1, $2, $3, $4::jsonb)`, [
289
+ entry.connection,
290
+ entry.id,
291
+ atOf(entry),
292
+ stored(entry),
293
+ ]);
294
+ await prune(client, entry.connection);
295
+ }),
296
+ update: (entry) => host.withWriteClient(async (client) => {
297
+ await client.query(`UPDATE ${pgEntry} SET entry = $1::jsonb WHERE connection = $2 AND id = $3`, [
298
+ stored(entry),
299
+ entry.connection,
300
+ entry.id,
301
+ ]);
302
+ }),
303
+ remove: (connection, id) => host.withWriteClient(async (client) => {
304
+ await client.query(`DELETE FROM ${pgEntry} WHERE connection = $1 AND id = $2`, [connection, id]);
305
+ }),
306
+ };
307
+ }
308
+ /**
309
+ * The store an adapter's database holds, or undefined where it holds none of
310
+ * it (the journal then stays in memory). An adapter a wrapper narrowed is
311
+ * looked through to the one it wraps. Throws WriteJournalUnavailable for a
312
+ * layout that is not this build's.
313
+ */
314
+ async function writeJournalStoreOf(adapter) {
315
+ const host = storeHostOf(adapter) ?? storeHostOf(writeViewOf(adapter)?.over);
316
+ if (!host)
317
+ return undefined;
318
+ if (host.dialect === 'sqlite') {
319
+ const db = host.reader();
320
+ if (!sqliteCatalog(db).length)
321
+ return undefined;
322
+ if (!sqliteWriteJournalReady(db))
323
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', sqliteLayoutVersion(db, META), WRITE_JOURNAL_VERSION));
324
+ return sqliteStore(host);
325
+ }
326
+ return host.withReadClient(async (client) => {
327
+ if (!(await pgRelations(client)).count)
328
+ return undefined;
329
+ if (!(await postgresWriteJournalReady(client)))
330
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', await postgresLayoutVersion(client, pgMeta), WRITE_JOURNAL_VERSION));
331
+ return postgresStore(host);
332
+ });
333
+ }
334
+ /**
335
+ * Keep `connection`'s journal in its database when the database holds the
336
+ * store: what it held is read back, and every write from here on is kept
337
+ * there too. Never fatal: a store that cannot be read leaves the journal in
338
+ * memory, said through `warn`. Resolves to whether the store is now used.
339
+ */
340
+ export async function keepWriteJournal(connection, adapter, warn = (message) => console.error(message)) {
341
+ try {
342
+ const store = await writeJournalStoreOf(adapter);
343
+ if (!store)
344
+ return false;
345
+ await attachJournalStore(connection, store, warn);
346
+ return true;
347
+ }
348
+ catch (error) {
349
+ warn(`"${connection}": Undo history is kept in memory for this run: ${error.message}`);
350
+ return false;
351
+ }
352
+ }
@@ -29,7 +29,7 @@ import { compareVersions, newMigration, readMigrations } from './files.js';
29
29
  import { FLYWAY_COMMANDS, runFlyway } from './flyway.js';
30
30
  import { migrateBaseline, migrateRepair, migrateUp, migrateValidate, migrationStatus, recordAround } from './runner.js';
31
31
  import { sayChange } from './snapshot.js';
32
- import { resolveTarget, targetDir } from './target.js';
32
+ import { migrateWriteRefusal, resolveTarget, targetDir } from './target.js';
33
33
  import { product } from '../product.js';
34
34
  import { claimContext, contextJson, contextLines, fromProfile, projectContext } from '../config/profile.js';
35
35
  const migrateUsage = () => product() +
@@ -89,6 +89,8 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
89
89
  'With --app, status prints the bootstrap plan (migrations, stores, sign-in store, seed, check) and up carries it out:\n' +
90
90
  ' the stores the App uses (--commands, --jobs, --policy name its modules), a PostgreSQL auth.store, then the check.\n' +
91
91
  ' validate --app exits 2 while any phase is pending. --json prints the plan as data.\n' +
92
+ 'up, baseline and repair write to the database: without --app, a connection a config names must say "writable": true\n' +
93
+ '(a database named with --db, and --dry-run, are not asked).\n' +
92
94
  'Exit codes: 1 could not run, 2 files and history disagree, 3 a migration failed, 4 applied but the App no longer checks,\n' +
93
95
  '5 a store step failed.\n' +
94
96
  'mistri docs migrate is the guide.');
@@ -278,6 +280,11 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
278
280
  return EXIT.ok;
279
281
  }
280
282
  const target = await resolveTarget(registry, config, flags, appDir, loaded?.binding);
283
+ /* An App's own database is the App's to migrate (`--app`): the plan it carries out is the deployment, and the
284
+ connection is the one it binds. The database browser, and a run with no App, answer to the flag. */
285
+ const refused = loaded ? undefined : migrateWriteRefusal(target.connection, command, dryRun);
286
+ if (refused)
287
+ return fail(refused);
281
288
  if (DESIRED.includes(command)) {
282
289
  const file = schemaFile !== undefined ? resolve(schemaFile) : defaultSchemaFile(target.dir);
283
290
  /* The first migration is schema.sql itself: written before any diff tool
@@ -27,6 +27,14 @@ interface ResolvedTarget extends MigrateTarget {
27
27
  }
28
28
  /** The connection the run is about: named, the App's home source's, or the only one. `tablewalk seed` reads it the same way. */
29
29
  export declare function targetConnection(registry: Registry, flags: Pick<TargetFlags, 'connection' | 'argument'>, binding?: TargetBinding, purpose?: string): ConnectionConfig;
30
+ /**
31
+ * Why a run may not write to this connection, or undefined. `"writable": true` is the config's statement about one
32
+ * named database (connections.ts), enforced wherever the server writes; migrate wrote DDL and its history table to a
33
+ * connection that said nothing of the kind. Only a connection a config names carries the flag: a database handed
34
+ * over on the command line (`<db>`, --db, DATABASE_URL) is the person's own act, as it always was, and a run that
35
+ * only prints a plan writes nothing, so neither is refused.
36
+ */
37
+ export declare function migrateWriteRefusal(connection: ConnectionConfig, command: string, dryRun?: boolean): string | undefined;
30
38
  /** The directory alone, for `migrate new`, which writes a file and opens no database. */
31
39
  export declare function targetDir(registry: Registry, config: StartupConfig, flags: TargetFlags, appDir?: string, binding?: TargetBinding): string;
32
40
  export declare function resolveTarget(registry: Registry, config: StartupConfig, flags: TargetFlags, appDir?: string, binding?: TargetBinding): Promise<ResolvedTarget>;
@@ -38,6 +38,21 @@ export function targetConnection(registry, flags, binding, purpose = 'migrate')
38
38
  throw new Error(`several connections are configured (${configs.map((config) => config.name).join(', ')}): name one with --connection.`);
39
39
  throw new Error(`no database to ${purpose}. Name it — a SQLite file, --db <url>, or --config <file> — or keep a ${configFileName()} beside where you run it.`);
40
40
  }
41
+ /** The commands that write DDL and history to the database; the rest only read it. */
42
+ const WRITING = new Set(['up', 'baseline', 'repair']);
43
+ /**
44
+ * Why a run may not write to this connection, or undefined. `"writable": true` is the config's statement about one
45
+ * named database (connections.ts), enforced wherever the server writes; migrate wrote DDL and its history table to a
46
+ * connection that said nothing of the kind. Only a connection a config names carries the flag: a database handed
47
+ * over on the command line (`<db>`, --db, DATABASE_URL) is the person's own act, as it always was, and a run that
48
+ * only prints a plan writes nothing, so neither is refused.
49
+ */
50
+ export function migrateWriteRefusal(connection, command, dryRun = false) {
51
+ if (!WRITING.has(command) || dryRun || connection.source !== 'config' || connection.writable)
52
+ return undefined;
53
+ return (`"${connection.name}" is not writable, and ${command} changes its schema and its history table. ` +
54
+ `Set "writable": true on the connection in ${configFileName()} to allow it, or name the database with --db <url> if it is one you mean to change.`);
55
+ }
41
56
  function directoryOf(connection, config, flags, appDir) {
42
57
  const base = config.configPath ? dirname(config.configPath) : process.cwd();
43
58
  return flags.migrations !== undefined
@@ -230,6 +230,9 @@ class Taken {
230
230
  function textFor(dice, plan, column, person, n, personLike, companyLike) {
231
231
  const name = column.name.toLowerCase();
232
232
  const table = plan.table;
233
+ /* A uuid column holds a uuid whatever it is called: `code` and `key` are words for text. */
234
+ if (/uuid/i.test(column.type))
235
+ return uuid(dice);
233
236
  if (/(^|_)e?mail(_address)?$/.test(name))
234
237
  return companyLike && !personLike
235
238
  ? `hello@${slug(person.company)}.example.com`
@@ -534,7 +537,7 @@ export async function seedDatabase(adapter, schema, opts) {
534
537
  if (column.nullable)
535
538
  values[column.name] = null;
536
539
  else
537
- ok = false;
540
+ throw new SeedRefusal(`${table.name}.${column.name} references ${ref.table}.${ref.column}, which has no rows to point at, so no ${table.name} row can be made.`);
538
541
  continue;
539
542
  }
540
543
  /* The first rows go one to each parent, so none is childless; the rest favor a few, as a busy doctor or a
@@ -548,8 +551,21 @@ export async function seedDatabase(adapter, schema, opts) {
548
551
  let order = ordersOf.get(column.name);
549
552
  if (!order)
550
553
  ordersOf.set(column.name, (order = crowd(dice, options)));
551
- if (!covering && (table.unique ?? []).includes(column.name)) {
552
- ok = false;
554
+ /* A reference that is unique (a primary key that is also a foreign key: a profile is its customer's) draws
555
+ each parent once, whatever the reference is called or typed; it is never made distinct by editing the key. */
556
+ if ((table.unique ?? []).includes(column.name) || (column.primaryKey && primary.length === 1)) {
557
+ const free = order.rows.find((row) => !taken.has(`${table.id}.${column.name}`, row[ref.column]));
558
+ if (!free) {
559
+ if (made > 0) {
560
+ ok = false;
561
+ continue;
562
+ }
563
+ throw new SeedRefusal(`${table.name}.${column.name} is unique and references ${ref.table}.${ref.column}, which has ${options.length} ${options.length === 1 ? 'row' : 'rows'}` +
564
+ ` and every one already has a ${table.name} row, so there is no key left to give it.` +
565
+ ' Add rows to the parent, or leave this table out.');
566
+ }
567
+ parents.set(column.name, free);
568
+ values[column.name] = free[ref.column];
553
569
  continue;
554
570
  }
555
571
  const parent = covering ? order.rows[made] : order.pick(dice);
@@ -690,30 +706,49 @@ export async function seedDatabase(adapter, schema, opts) {
690
706
  }
691
707
  }
692
708
  }
693
- /* Never repeat what must be unique: a second "Ada Lam" gets a number, a second pair is skipped. */
709
+ /* Never repeat what must be unique, in the column's own terms: a second "Ada Lam" gets a number, a uuid a fresh
710
+ uuid, a date the next day, an integer the next integer; a second pair is skipped. A reference is drawn above. */
694
711
  for (const column of table.unique ?? []) {
695
712
  const key = `${table.id}.${column}`;
696
713
  const value = values[column];
697
- if (value === undefined || value === null)
714
+ if (value === undefined || value === null || plan.refs.has(column))
698
715
  continue;
699
716
  if (!taken.has(key, value))
700
717
  continue;
718
+ const meta = table.columns.find((c) => c.name === column);
719
+ const kind = moment(meta, types);
701
720
  let changed;
702
721
  for (let k = 2; k < 1000 && changed === undefined; k++) {
703
- const next = typeof value === 'number'
704
- ? value + k * 1000
705
- : /@/.test(String(value))
706
- ? String(value).replace('@', `${k}@`)
707
- : `${value} ${k}`;
722
+ const next = /uuid/i.test(meta.type)
723
+ ? uuid(dice)
724
+ : kind
725
+ ? (() => {
726
+ const at = new Date(String(value));
727
+ return Number.isNaN(at.getTime()) ? undefined : written(new Date(at.getTime() + (k - 1) * DAY), kind);
728
+ })()
729
+ : typeof value === 'number'
730
+ ? value + (k - 1)
731
+ : /@/.test(String(value))
732
+ ? String(value).replace('@', `${k}@`)
733
+ : `${value} ${k}`;
734
+ if (next === undefined)
735
+ break;
708
736
  if (!taken.has(key, next))
709
737
  changed = next;
710
738
  }
739
+ if (changed === undefined && !meta.nullable)
740
+ throw new SeedRefusal(`${table.name}.${column} must be unique, and no new ${meta.type || 'value'} could be made that is not already taken.`);
711
741
  values[column] = changed ?? null;
712
742
  }
713
743
  const pairKeys = pairs.map(([a, b]) => `${table.id}.${a}+${b}`);
714
744
  if (pairs.some(([a, b], i) => values[a] != null && values[b] != null && taken.has(pairKeys[i], `${values[a]}\u0000${values[b]}`)))
715
745
  continue;
716
- const inserted = await tx.insert({ table: table.id, values });
746
+ const inserted = await tx.insert({ table: table.id, values }).catch((error) => {
747
+ if (error instanceof SeedRefusal)
748
+ throw error;
749
+ const column = error.column;
750
+ throw new SeedRefusal(`${table.name}${typeof column === 'string' && column ? `.${column}` : ''}: ${error instanceof Error ? error.message : String(error)}`);
751
+ });
717
752
  const row = { ...values, ...(inserted.row ?? {}), ...inserted.key };
718
753
  for (const column of table.unique ?? [])
719
754
  if (row[column] != null)
@@ -69,6 +69,10 @@ export interface AppCardsList {
69
69
  }
70
70
  /** How many facts a card carries under its title. */
71
71
  export declare const CARDS_MAX_LINES = 4;
72
+ /** How many facts a record header says before the rest wait in its More: the first of them stay in the line. */
73
+ export declare const HEADER_FACTS_SHOWN = 6;
74
+ /** How many a header may name at all; past the line they fold, so an author never moves one into a side block to fit. */
75
+ export declare const HEADER_MAX_FACTS = 12;
72
76
  /** One sort key and its direction: "position", "added_at desc". */
73
77
  export declare function cardsImageSort(sort: string): {
74
78
  column: string;
@@ -27,6 +27,10 @@ import { singularOf } from './unitWord.js';
27
27
  export const CARDS_MAX_LINES = 4;
28
28
  /** How many values a card's facts line says. */
29
29
  const CARDS_MAX_FACTS = 6;
30
+ /** How many facts a record header says before the rest wait in its More: the first of them stay in the line. */
31
+ export const HEADER_FACTS_SHOWN = 6;
32
+ /** How many a header may name at all; past the line they fold, so an author never moves one into a side block to fit. */
33
+ export const HEADER_MAX_FACTS = 12;
30
34
  /** How many values stand along a card's foot. */
31
35
  const CARDS_MAX_FOOTER = 4;
32
36
  const CARDS_IMAGE_KEYS = ['about', 'from', 'whose', 'sort'];
@@ -88,6 +92,7 @@ export function parseFacts(raw, at, key = 'facts', max = CARDS_MAX_FACTS) {
88
92
  allowKeys(entry, ['column', 'before', 'after'], `${at}, ${key}`, {
89
93
  label: 'is now "after" (a word after the value) or "before" (a word before it)',
90
94
  position: 'is gone: "before" is a word before the value, "after" a word after it',
95
+ subtitle: 'is the second line of a headline figure (headline(figure, { subtitle })); a fact is one line, so its words go in "before" or "after"',
91
96
  });
92
97
  const path = entry.column.trim();
93
98
  const word = (value, which) => {
@@ -1,3 +1,10 @@
1
1
  import type { AppListPresentation } from './listPresentations.js';
2
+ /**
3
+ * The columns a presentation draws with their display rule's second line (`subtitle`), so a list reads it with the
4
+ * row: a card's title, its figure and its captioned lines, and a board card's title. A one-line place — a badge, a
5
+ * description, a card's summary and foot, a board card's line, chip and facts — has no room for one, and `check` says
6
+ * so where a subtitled column stands there (`subtitle-unseen`).
7
+ */
8
+ export declare function listSecondLineColumns(list: AppListPresentation): string[];
2
9
  /** A split reads through its own show, and the columns of its rows when it chooses them. */
3
10
  export declare function listPresentationColumns(list: AppListPresentation): string[];
@@ -6,6 +6,19 @@
6
6
  * homes it installs at load — into the first script it downloads.
7
7
  */
8
8
  import { cardsColumns } from './appCards.js';
9
+ /**
10
+ * The columns a presentation draws with their display rule's second line (`subtitle`), so a list reads it with the
11
+ * row: a card's title, its figure and its captioned lines, and a board card's title. A one-line place — a badge, a
12
+ * description, a card's summary and foot, a board card's line, chip and facts — has no room for one, and `check` says
13
+ * so where a subtitled column stands there (`subtitle-unseen`).
14
+ */
15
+ export function listSecondLineColumns(list) {
16
+ if (list.kind === 'cards')
17
+ return [...new Set([list.primary, ...(list.value ? [list.value] : []), ...(list.lines ?? [])])];
18
+ if (list.kind === 'board')
19
+ return [list.primary];
20
+ return [];
21
+ }
9
22
  /** A split reads through its own show, and the columns of its rows when it chooses them. */
10
23
  export function listPresentationColumns(list) {
11
24
  if (list.kind === 'split') {
@@ -434,8 +434,14 @@ function compileBreakdownFresh(schema, def, style, offset, scope) {
434
434
  if (!names.has(o.name)) {
435
435
  throw new PathError(`Nothing called "${o.name}" is in this breakdown. It shows: ${[...names].join(', ')}.`, o.name, o.name, 0);
436
436
  }
437
- if (o.emptyLast)
438
- return `(${style.quote(o.name)} IS NULL) ASC`;
437
+ /* An output name is only a name when it stands alone in ORDER BY: inside an expression PostgreSQL reads it as an
438
+ input column, and a key (`hold_id`) that the joined record also has (`holds.hold_id`) is ambiguous there. The
439
+ expression the SELECT list gives that name is what is tested. */
440
+ if (o.emptyLast) {
441
+ const shown = select[columns.findIndex((c) => c.name === o.name)] ?? style.quote(o.name);
442
+ const quoted = ` AS ${style.quote(o.name)}`;
443
+ return `(${shown.endsWith(quoted) ? shown.slice(0, -quoted.length) : shown} IS NULL) ASC`;
444
+ }
439
445
  /* An exact sum is text; it sorts by the integer it says, never as text ("9.00" after "10.00"). */
440
446
  return `${orderedBy.get(o.name) ?? style.quote(o.name)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`;
441
447
  });
@@ -34,7 +34,7 @@
34
34
  */
35
35
  import type { SqlStyle } from './filter.js';
36
36
  import type { ColumnMeta, DatabaseSchema } from './schema.js';
37
- export declare const COMPUTED_TYPES: readonly ['boolean', 'number', 'date'];
37
+ export declare const COMPUTED_TYPES: readonly ['boolean', 'number', 'date', 'text'];
38
38
  export type ComputedType = (typeof COMPUTED_TYPES)[number];
39
39
  /** A span a date moves by: `3 days`, `term months`. */
40
40
  export type ComputedUnit = ComputedSpan['unit'];
@@ -78,12 +78,26 @@ export type ComputedNode = {
78
78
  k: 'call';
79
79
  fn: ComputedFunction;
80
80
  args: ComputedNode[];
81
- } | {
81
+ } | ComputedJson | {
82
82
  k: 'op';
83
83
  op: ComputedOp;
84
84
  left: ComputedNode;
85
85
  right: ComputedNode;
86
86
  };
87
+ /**
88
+ * A member of a JSON column, read as text: `filters_json.make`, `payload.customer.city`. Authored as a path; the
89
+ * catalog that knows `filters_json` is a JSON column, and no reference, makes it this (appComputed.ts). Each key is
90
+ * an identifier (the tokenizer's word), so it is written into the statement's path literal as it stands. The
91
+ * database is never asked whether the member is there: one that is not has no value.
92
+ * @preview
93
+ */
94
+ export interface ComputedJson {
95
+ k: 'json';
96
+ /** The table's own JSON column. */
97
+ column: string;
98
+ /** The members walked, outermost first. */
99
+ keys: string[];
100
+ }
87
101
  /** The functions an expression may call (computedParse.ts COMPUTED_FUNCTIONS): each written alike on every engine and worked out alike in JavaScript. */
88
102
  export type ComputedFunction = 'coalesce' | 'round' | 'min' | 'max' | 'abs';
89
103
  interface ComputedSpan {