@mistriwork/engine 1.0.0-rc.10 → 1.0.0-rc.12

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 (93) hide show
  1. package/dist/adapters/adapter.d.ts +33 -0
  2. package/dist/adapters/postgres.d.ts +21 -16
  3. package/dist/adapters/postgres.js +199 -223
  4. package/dist/adapters/postgresCatalog.d.ts +12 -1
  5. package/dist/adapters/postgresCatalog.js +57 -23
  6. package/dist/adapters/postgresCatalogDigest.js +40 -34
  7. package/dist/adapters/postgresCatalogRows.d.ts +2 -0
  8. package/dist/adapters/postgresWriteAhead.d.ts +47 -0
  9. package/dist/adapters/postgresWriteAhead.js +209 -0
  10. package/dist/adapters/scoped/keyRows.js +9 -3
  11. package/dist/adapters/scoped/keyTypes.d.ts +34 -0
  12. package/dist/adapters/scoped/keyTypes.js +66 -0
  13. package/dist/adapters/scoped/postgresScopeCatalog.d.ts +40 -1
  14. package/dist/adapters/scoped/postgresScopeCatalog.js +417 -13
  15. package/dist/adapters/scoped/postgresTriggers.d.ts +137 -0
  16. package/dist/adapters/scoped/postgresTriggers.js +1545 -0
  17. package/dist/adapters/scoped/scopeTriggers.d.ts +122 -0
  18. package/dist/adapters/scoped/scopeTriggers.js +131 -0
  19. package/dist/adapters/scoped/scopedReads.d.ts +3 -1
  20. package/dist/adapters/scoped/scopedReads.js +28 -8
  21. package/dist/adapters/scoped/scopedTransaction.d.ts +95 -6
  22. package/dist/adapters/scoped/scopedTransaction.js +308 -34
  23. package/dist/adapters/scoped/sqliteScopeCatalog.d.ts +17 -1
  24. package/dist/adapters/scoped/sqliteScopeCatalog.js +197 -18
  25. package/dist/adapters/scoped/sqliteTriggerSession.d.ts +64 -0
  26. package/dist/adapters/scoped/sqliteTriggerSession.js +245 -0
  27. package/dist/adapters/scoped/sqliteTriggers.d.ts +20 -0
  28. package/dist/adapters/scoped/sqliteTriggers.js +822 -0
  29. package/dist/adapters/scoped/storedText.d.ts +45 -0
  30. package/dist/adapters/scoped/storedText.js +61 -0
  31. package/dist/adapters/scoped/triggerEffects.d.ts +98 -0
  32. package/dist/adapters/scoped/triggerEffects.js +189 -0
  33. package/dist/adapters/scoped/triggerProof.d.ts +124 -0
  34. package/dist/adapters/scoped/triggerProof.js +366 -0
  35. package/dist/adapters/snapshotRead.d.ts +8 -0
  36. package/dist/adapters/snapshotRead.js +37 -0
  37. package/dist/adapters/sqlite.d.ts +13 -2
  38. package/dist/adapters/sqlite.js +139 -16
  39. package/dist/adapters/sqliteDecimals.d.ts +2 -2
  40. package/dist/adapters/sqliteDecimals.js +2 -8
  41. package/dist/adapters/storeHost.d.ts +4 -1
  42. package/dist/adapters/writeCapture.d.ts +7 -0
  43. package/dist/server/cli/args.d.ts +6 -0
  44. package/dist/server/cli/args.js +6 -0
  45. package/dist/server/columnGrants.d.ts +3 -0
  46. package/dist/server/columnGrants.js +12 -1
  47. package/dist/server/config/profile.d.ts +123 -0
  48. package/dist/server/config/profile.js +236 -0
  49. package/dist/server/connections.d.ts +5 -0
  50. package/dist/server/connections.js +11 -1
  51. package/dist/server/hiddenColumns.js +6 -0
  52. package/dist/server/http/refusalReport.js +16 -4
  53. package/dist/server/http/router.d.ts +11 -22
  54. package/dist/server/http/router.js +0 -15
  55. package/dist/server/migrate/cli.d.ts +50 -3
  56. package/dist/server/migrate/cli.js +199 -14
  57. package/dist/server/migrate/runner.js +5 -1
  58. package/dist/server/shapeonly.js +5 -0
  59. package/dist/shared/addressParams.d.ts +2 -0
  60. package/dist/shared/addressParams.js +2 -0
  61. package/dist/shared/aggregate.d.ts +49 -0
  62. package/dist/shared/aggregate.js +107 -0
  63. package/dist/shared/breakdown.js +19 -6
  64. package/dist/shared/decimals.d.ts +37 -0
  65. package/dist/shared/decimals.js +148 -0
  66. package/dist/shared/displayDefaults.js +15 -1
  67. package/dist/shared/filter.d.ts +39 -1
  68. package/dist/shared/filter.js +96 -15
  69. package/dist/shared/listPresentations.d.ts +2 -0
  70. package/dist/shared/listQuestion.d.ts +3 -1
  71. package/dist/shared/money.d.ts +9 -0
  72. package/dist/shared/money.js +17 -0
  73. package/dist/shared/moneyEntry.d.ts +6 -3
  74. package/dist/shared/moneyEntry.js +14 -7
  75. package/dist/shared/pageModel.d.ts +1 -1
  76. package/dist/shared/recordview.d.ts +1 -1
  77. package/dist/shared/refusal.d.ts +16 -0
  78. package/dist/shared/refusal.js +40 -0
  79. package/dist/shared/rowScope.js +12 -4
  80. package/dist/shared/schema.d.ts +6 -0
  81. package/dist/shared/schematext.d.ts +22 -6
  82. package/dist/shared/schematext.js +18 -2
  83. package/dist/shared/scopeCatalog.js +4 -0
  84. package/dist/shared/servedApp.d.ts +15 -4
  85. package/dist/shared/view.js +4 -4
  86. package/dist/shared/viewLabels.d.ts +1 -0
  87. package/dist/shared/viewLabels.js +8 -2
  88. package/dist/shared/viewPaths.d.ts +3 -0
  89. package/dist/shared/viewPaths.js +8 -0
  90. package/package.json +5 -2
  91. package/schema/model.d.ts +1 -1
  92. package/dist/shared/order.d.ts +0 -59
  93. package/dist/shared/order.js +0 -133
@@ -0,0 +1,236 @@
1
+ /**
2
+ * The project profile (docs/bootstrap-plan.md, Part B): the `app` block of `mistri.json`, which names the App and
3
+ * the modules that carry its authority once, and the one rule every App command finds that file by.
4
+ *
5
+ * ```json
6
+ * { "app": { "dir": ".", "commands": "commands.ts", "jobs": "jobs.ts", "policy": "policy.ts" }, "connections": [...] }
7
+ * ```
8
+ *
9
+ * The order is fixed and printed: `--config`, then the App's own `<--app dir>/mistri.json`, then `./mistri.json`
10
+ * and `./.mistri.json`, then the person's own file. No walking up. Without `--app`, the found file's `app.dir`
11
+ * names the App. A flag beats the profile, and the profile beats the `commands.ts` convention; there is no
12
+ * environment layer, since the environment is for secrets. A field report found `dev scratch` and
13
+ * `check --app scratch` reading different files, and `--policy` repeated on every command of a tenant App.
14
+ *
15
+ * The block takes paths and nothing else: a `${NAME}` reference, a key it does not know, or a file that is not
16
+ * there is refused by name. It is not a second App definition: it names modules and defines nothing.
17
+ */
18
+ import { existsSync, readFileSync } from 'node:fs';
19
+ import { homedir } from 'node:os';
20
+ import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
21
+ import { configFileName, product } from '../product.js';
22
+ /** An entry the block may name, and the flag it stands for. */
23
+ const PROFILE_ENTRIES = { commands: '--commands', jobs: '--jobs', policy: '--policy', entry: '--app-entry' };
24
+ const PROFILE_KEYS = ['dir', ...Object.keys(PROFILE_ENTRIES)];
25
+ /** A profile that cannot be used: refused before anything is read. */
26
+ export class ProfileRefusal extends Error {
27
+ }
28
+ const shown = (path) => {
29
+ const near = relative(process.cwd(), path);
30
+ return !near ? '.' : near.startsWith('..') || isAbsolute(near) ? path : near;
31
+ };
32
+ /**
33
+ * The config file a run reads, by the one order: `--config`, the App's own, the working directory's, the person's
34
+ * own. Undefined when there is none (a run on a database named by `--db`).
35
+ */
36
+ export function findConfig(given, env = process.env) {
37
+ if (given.explicit !== undefined)
38
+ return { path: resolve(given.explicit), from: 'flag' };
39
+ const name = configFileName();
40
+ if (given.app !== undefined && existsSync(join(resolve(given.app), name)))
41
+ return { path: join(resolve(given.app), name), from: 'app' };
42
+ for (const path of [join(process.cwd(), name), join(process.cwd(), `.${name}`)])
43
+ if (existsSync(path))
44
+ return { path, from: 'cwd' };
45
+ const user = join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), product(), 'connections.json');
46
+ return existsSync(user) ? { path: user, from: 'user' } : undefined;
47
+ }
48
+ /** The `app` block of `file`, checked; undefined when the file has none. Throws a ProfileRefusal naming what is wrong. */
49
+ export function readProfile(file) {
50
+ let parsed;
51
+ try {
52
+ parsed = JSON.parse(readFileSync(file, 'utf8'));
53
+ }
54
+ catch {
55
+ /* A file that does not parse is the config reader's to refuse, with its own words. */
56
+ return undefined;
57
+ }
58
+ if (!parsed || typeof parsed !== 'object' || !('app' in parsed))
59
+ return undefined;
60
+ const block = parsed.app;
61
+ const at = shown(file);
62
+ if (parsed.apps !== undefined)
63
+ throw new ProfileRefusal(`${at} has both "app" and "apps": "app" names the one App this project is, "apps" lists the Apps one server serves. Keep one.`);
64
+ if (!block || typeof block !== 'object' || Array.isArray(block))
65
+ throw new ProfileRefusal(`${at}: "app" is an object of paths, like { "dir": ".", "jobs": "jobs.ts" }.`);
66
+ const unknown = Object.keys(block).filter((key) => !PROFILE_KEYS.includes(key));
67
+ if (unknown.length)
68
+ throw new ProfileRefusal(`${at}: app.${unknown[0]} is not a key of the app block. It takes ${PROFILE_KEYS.slice(0, -1).join(', ')} and ${PROFILE_KEYS.at(-1)}: the App and the modules that carry its authority. Ports, mounts and looks stay as flags.`);
69
+ const folder = dirname(file);
70
+ const profile = { file };
71
+ for (const [key, value] of Object.entries(block)) {
72
+ if (typeof value !== 'string' || !value.trim())
73
+ throw new ProfileRefusal(`${at}: app.${key} is a path, relative to ${at}'s folder.`);
74
+ if (/\$\{|\$[A-Z_]/.test(value))
75
+ throw new ProfileRefusal(`${at}: app.${key} names ${JSON.stringify(value)}. The app block takes paths only: a secret or a value that differs per machine stays in the environment.`);
76
+ const path = resolve(folder, value);
77
+ if (!existsSync(path))
78
+ throw new ProfileRefusal(`${at}: app.${key} names ${value}, which is not there (${shown(path)}, from ${shown(folder)}).`);
79
+ profile[key] = path;
80
+ }
81
+ return profile;
82
+ }
83
+ let resolved;
84
+ let said = false;
85
+ /**
86
+ * Whether the context is still to be said: true once a run, so a check `migrate up --app` runs inside it does not
87
+ * say it again after the migrate run said it first.
88
+ */
89
+ export function claimContext() {
90
+ if (said)
91
+ return false;
92
+ said = true;
93
+ return true;
94
+ }
95
+ /** The context the run's profile step resolved (applyProfile), for the command to print. */
96
+ export const projectContext = () => resolved;
97
+ /** Value of a flag in argv (`--flag value`), and every index it is at. */
98
+ function flagged(argv, flag) {
99
+ const values = [];
100
+ for (let i = 0; i < argv.length; i++)
101
+ if (argv[i] === flag && argv[i + 1] !== undefined)
102
+ values.push(argv[i + 1]);
103
+ return values;
104
+ }
105
+ /**
106
+ * The run's arguments with the profile applied under them: the App when no `--app` names one, each entry the
107
+ * command takes that no flag names, and `--config` pinned where the file found is not the one a plain read would
108
+ * find (the App's own `mistri.json`), so the run and any child it starts read the same file. Records the context.
109
+ * Throws a ProfileRefusal for a block that cannot be used.
110
+ */
111
+ export function applyProfile(argv, takes, env = process.env) {
112
+ const out = [...argv];
113
+ if (out.includes('--no-config') || out.includes('--help') || out.includes('-h')) {
114
+ resolved = undefined;
115
+ return out;
116
+ }
117
+ /* A suite's Apps are the suite's to name (`migrate stores up --suite`): the profile's one App is not added to it. */
118
+ const suite = out.includes('--suite');
119
+ const apps = flagged(out, '--app');
120
+ const positional = takes.positional && out[0] !== undefined && !out[0].startsWith('-') ? out[0] : undefined;
121
+ const named = apps.length === 1 ? apps[0] : positional;
122
+ const explicit = flagged(out, '--config').at(-1);
123
+ const naming = out.includes('--db') || out.includes('-d');
124
+ const found = naming && explicit === undefined
125
+ ? undefined
126
+ : findConfig({ ...(explicit !== undefined ? { explicit } : {}), ...(named !== undefined ? { app: named } : {}) }, env);
127
+ /* The person's own file names connections; a project's profile is a project's, so it is never read from there. */
128
+ const profile = found && found.from !== 'user' ? readProfile(found.path) : undefined;
129
+ const over = {};
130
+ let app;
131
+ if (apps.length > 1)
132
+ app = undefined;
133
+ else if (named !== undefined) {
134
+ app = { path: resolve(named), from: 'flag' };
135
+ if (profile?.dir !== undefined && resolve(named) !== profile.dir)
136
+ over.dir = profile.dir;
137
+ }
138
+ else if (profile?.dir !== undefined && !suite && takes.app !== false) {
139
+ app = { path: profile.dir, from: 'profile' };
140
+ out.push('--app', shown(profile.dir));
141
+ }
142
+ const entries = {};
143
+ if (apps.length <= 1 && !suite && takes.app !== false)
144
+ for (const entry of takes.entries) {
145
+ const flag = PROFILE_ENTRIES[entry];
146
+ const given = flagged(out, flag).at(-1);
147
+ const said = profile?.[entry];
148
+ if (given !== undefined) {
149
+ entries[entry] = { path: resolve(given), from: 'flag' };
150
+ if (said !== undefined && resolve(given) !== said)
151
+ over[entry] = said;
152
+ }
153
+ else if (said !== undefined) {
154
+ entries[entry] = { path: said, from: 'profile' };
155
+ out.push(flag, shown(said));
156
+ }
157
+ }
158
+ /* The App's own file is not one a plain read finds (engine config/locations.ts reads the working directory's):
159
+ named, so this run and the children it starts read it. */
160
+ if (found?.from === 'app' && explicit === undefined)
161
+ out.push('--config', shown(found.path));
162
+ resolved = { ...(found ? { config: found } : {}), ...(app ? { app } : {}), entries, over };
163
+ said = false;
164
+ return out;
165
+ }
166
+ /** Whether the profile, or the App's own mistri.json, decided any of the run's context: then the run says it. */
167
+ export function fromProfile(context) {
168
+ return (context !== undefined &&
169
+ (context.config?.from === 'app' ||
170
+ context.app?.from === 'profile' ||
171
+ Object.values(context.entries).some((entry) => entry.from === 'profile') ||
172
+ Object.keys(context.over).length > 0));
173
+ }
174
+ /**
175
+ * The entries the App itself says, where neither a flag nor the profile named one: the `commands.ts` beside its
176
+ * manifest (convention), or a build's own bundles (build).
177
+ */
178
+ export function appEntries(app, given) {
179
+ const more = {};
180
+ if (app.build) {
181
+ for (const kind of ['commands', 'jobs', 'policy']) {
182
+ const own = app.build.entries[kind];
183
+ if (own && given[kind] === undefined)
184
+ more[kind] = { path: own, from: 'build' };
185
+ }
186
+ return more;
187
+ }
188
+ if (given.commands === undefined && app.commands)
189
+ more.commands = { path: app.commands.file, from: 'convention' };
190
+ return more;
191
+ }
192
+ /**
193
+ * The context as the run prints it, one line an entry: where it came from, and a flag that overrode the profile.
194
+ * `convention` and `build` are the App's to say (the loaded App's commands.ts beside it, a build's own bundles).
195
+ */
196
+ export function contextLines(context, more = {}) {
197
+ if (!context)
198
+ return [];
199
+ const where = context.config
200
+ ? `${shown(context.config.path)} (${{ flag: '--config', app: 'beside the App', cwd: 'the working directory', user: "the person's own" }[context.config.from]})`
201
+ : 'no config file';
202
+ const lines = [`Context: ${where}`];
203
+ const row = (key, path, from) => lines.push(` ${key.padEnd(9)} ${(path ?? '—').padEnd(13)} ${from}`);
204
+ if (context.app)
205
+ row('app', shown(context.app.path), context.app.from === 'profile' ? 'mistri.json' : over(context, 'dir', 'flag'));
206
+ for (const entry of ['commands', 'jobs', 'policy', 'entry']) {
207
+ const own = context.entries[entry] ?? more[entry];
208
+ if (!own) {
209
+ /* Not named by a flag or the profile: the App may still say it (its commands.ts), where the run reads that. */
210
+ if (entry !== 'entry')
211
+ row(entry, undefined, 'not named');
212
+ continue;
213
+ }
214
+ row(entry, shown(own.path), own.from === 'profile' ? 'mistri.json' : own.from === 'flag' ? over(context, entry, 'flag') : own.from);
215
+ }
216
+ return lines;
217
+ }
218
+ function over(context, key, from) {
219
+ const said = context.over[key];
220
+ return said !== undefined ? `${from}, over mistri.json's ${shown(said)}` : from;
221
+ }
222
+ /** The context as `--json` carries it: `{ config, app, entries: { commands|jobs|policy|entry: { path, from } | null } }`. */
223
+ export function contextJson(context, more = {}) {
224
+ const entry = (key) => {
225
+ const own = context?.entries[key] ?? more[key];
226
+ if (!own)
227
+ return null;
228
+ const said = context?.over[key];
229
+ return { path: own.path, from: own.from, ...(said !== undefined ? { over: said } : {}) };
230
+ };
231
+ return {
232
+ config: context?.config ?? null,
233
+ app: context?.app ?? null,
234
+ entries: { commands: entry('commands'), jobs: entry('jobs'), policy: entry('policy'), entry: entry('entry') },
235
+ };
236
+ }
@@ -167,6 +167,11 @@ export declare class Registry {
167
167
  configOf(id: string): ConnectionConfig | undefined;
168
168
  /** Every stored configuration, in order, including its secrets as written. */
169
169
  configs(): ConnectionConfig[];
170
+ /**
171
+ * One connection's URL as opening it would read it (see `openableUrls`): what a store beside it must be
172
+ * located by, since the stored text may be a `${VAR}` reference.
173
+ */
174
+ openableUrlOf(id: string): string | undefined;
170
175
  /**
171
176
  * Each database connection's URL as opening it would read it: `${VAR}` references resolved through this
172
177
  * registry's captured environment (an untrusted URL as written), an API's left out. Read in one pass with no
@@ -208,6 +208,16 @@ export class Registry {
208
208
  configs() {
209
209
  return [...this.entries.values()].map((e) => e.config);
210
210
  }
211
+ /**
212
+ * One connection's URL as opening it would read it (see `openableUrls`): what a store beside it must be
213
+ * located by, since the stored text may be a `${VAR}` reference.
214
+ */
215
+ openableUrlOf(id) {
216
+ const entry = this.entries.get(id);
217
+ if (!entry)
218
+ return undefined;
219
+ return entry.untrustedUrl ? entry.config.url : expandEnv(entry.config.url, this.environment);
220
+ }
211
221
  /**
212
222
  * Each database connection's URL as opening it would read it: `${VAR}` references resolved through this
213
223
  * registry's captured environment (an untrusted URL as written), an API's left out. Read in one pass with no
@@ -218,7 +228,7 @@ export class Registry {
218
228
  for (const entry of this.entries.values()) {
219
229
  if (entry.config.http)
220
230
  continue;
221
- urls.push(entry.untrustedUrl ? entry.config.url : expandEnv(entry.config.url, this.environment));
231
+ urls.push(this.openableUrlOf(entry.config.id));
222
232
  }
223
233
  return urls;
224
234
  }
@@ -152,6 +152,7 @@ export function hideColumns(adapter, name, rules, introspected) {
152
152
  ...(inner.lockRecord ? { lockRecord: guard(inner.lockRecord) } : {}),
153
153
  query: guard(inner.query),
154
154
  count: guard(inner.count),
155
+ ...(inner.aggregate ? { aggregate: guard(inner.aggregate) } : {}),
155
156
  insert: guard(inner.insert),
156
157
  update: guard(inner.update),
157
158
  remove: guard(inner.remove),
@@ -165,6 +166,7 @@ export function hideColumns(adapter, name, rules, introspected) {
165
166
  countView: (view, limit) => bound.countView(checked(() => checks.viewFor(view)), limit),
166
167
  runBreakdown: (def, offset) => bound.runBreakdown(checked(() => checks.breakdownFor(def)), offset),
167
168
  countBreakdown: (def, limit) => bound.countBreakdown(checked(() => checks.breakdownFor(def)), limit),
169
+ ...(bound.aggregate ? { aggregate: (request) => bound.aggregate(checked(() => checks.aggregateFor(request))) } : {}),
168
170
  });
169
171
  const wrapped = Object.create(Object.getPrototypeOf(adapter));
170
172
  Object.assign(wrapped, adapter);
@@ -177,6 +179,8 @@ export function hideColumns(adapter, name, rules, introspected) {
177
179
  wrapped.poolStats = from('poolStats');
178
180
  if (adapter.privileges)
179
181
  wrapped.privileges = from('privileges');
182
+ if (adapter.triggers)
183
+ wrapped.triggers = from('triggers');
180
184
  if (adapter.estimateCount)
181
185
  wrapped.estimateCount = from('estimateCount');
182
186
  wrapped.query = async (request) => adapter.query(checked(() => checks.queryFor(request)));
@@ -191,6 +195,8 @@ export function hideColumns(adapter, name, rules, introspected) {
191
195
  wrapped.runBreakdown = async (def, offset) => adapter.runBreakdown(checked(() => checks.breakdownFor(def)), offset);
192
196
  if (adapter.countBreakdown)
193
197
  wrapped.countBreakdown = async (def, limit) => adapter.countBreakdown(checked(() => checks.breakdownFor(def)), limit);
198
+ if (adapter.aggregate)
199
+ wrapped.aggregate = async (request) => adapter.aggregate(checked(() => checks.aggregateFor(request)));
194
200
  if (adapter.scopeReads)
195
201
  wrapped.scopeReads = async (scope) => reads(await adapter.scopeReads(scope));
196
202
  /* Raw SQL can name any column, in any spelling, through any function: no
@@ -1,4 +1,4 @@
1
- import { refusalReasons, refusalSaid } from '../../shared/refusal.js';
1
+ import { isAuthorFault, refusalReasons, refusalSaid } from '../../shared/refusal.js';
2
2
  import { clientTrusted } from './trust.js';
3
3
  import { AppAccessDenied } from '../columnGrants.js';
4
4
  import { TenantContextError } from '../evidence.js';
@@ -55,9 +55,21 @@ export function reportRefusal(req, status, code, heard, error, always = false) {
55
55
  if (status < 500 && !recorded(error).length && !refusalSaid(error) && !always)
56
56
  return undefined;
57
57
  const path = (req.url ?? '').split('?')[0];
58
- console.error(`${product()}: ${req.method ?? 'GET'} ${path} refused (${status}${code ? ` ${code}` : ''})${heard ? `: ${heard}` : ''}`);
59
- for (const reason of reasons)
60
- console.error(` because: ${reason}`);
58
+ const refused = `${product()}: ${req.method ?? 'GET'} ${path} refused (${status}${code ? ` ${code}` : ''})`;
59
+ /* The author's own mistake leads with what to fix; the sentence its caller was told follows, as what it was. */
60
+ const fault = isAuthorFault(error) ? reasons.at(-1) : undefined;
61
+ if (fault) {
62
+ console.error(`${refused}: ${fault}`);
63
+ for (const reason of reasons.slice(0, -1))
64
+ console.error(` because: ${reason}`);
65
+ if (heard)
66
+ console.error(` callers are told: ${heard}`);
67
+ }
68
+ else {
69
+ console.error(`${refused}${heard ? `: ${heard}` : ''}`);
70
+ for (const reason of reasons)
71
+ console.error(` because: ${reason}`);
72
+ }
61
73
  // The innermost reason is the one that names the rule, the table or the column.
62
74
  return authors.has(req) ? reasons.at(-1) : undefined;
63
75
  }
@@ -18,28 +18,17 @@ export type Route<C extends RequestContext> = (ctx: C) => boolean | Promise<bool
18
18
  /** Try `routes` in order; true when one answered. */
19
19
  export declare function route<C extends RequestContext>(ctx: C, routes: readonly Route<C>[]): Promise<boolean>;
20
20
  /**
21
- * Every dispatcher: a module that takes a request from a socket (or a host's
21
+ * A dispatcher: a module that takes a request from a socket (or a host's
22
22
  * server) and holds it to the door before any route reads it, in the door's
23
23
  * order — the Host, the proxy's identity, the product's session, then a
24
- * write's Origin and body. test/door.test.ts stands each up and sends it the
25
- * same refusals; a new one is named here, and given a row there.
24
+ * write's Origin and body. Each product names its own in a table of these
25
+ * (its server/http/dispatchers.ts), so the engine names no product's path;
26
+ * test/door.test.ts stands each up and sends it the same refusals, and a new
27
+ * one is named in its product's table and given a row there.
26
28
  */
27
- export declare const DISPATCHERS: readonly [{
28
- readonly module: 'packages/tablewalk/src/server/http/browserHandler.ts';
29
- readonly serves: 'the database browser';
30
- }, {
31
- readonly module: 'packages/mistri/src/server/http/handler.ts';
32
- readonly serves: 'the Apps of a deployment that serves them';
33
- }, {
34
- readonly module: 'packages/mistri/src/server/embed/handler.ts';
35
- readonly serves: 'an App mounted inside somebody else’s server';
36
- }, {
37
- readonly module: 'packages/mistri/src/server/http/suite.ts';
38
- readonly serves: 'several deployments under one origin, each behind its own dispatcher';
39
- }, {
40
- readonly module: 'packages/mistri/src/server/tenant/tenantAuthenticatedHttp.ts';
41
- readonly serves: 'a tenant App’s browser host and its native sign-in';
42
- }, {
43
- readonly module: 'packages/mistri/src/server/tenant/tenantHttp.ts';
44
- readonly serves: 'a tenant App’s data, inside its browser host';
45
- }];
29
+ export interface Dispatcher {
30
+ /** The module, by its path in the repository. */
31
+ readonly module: string;
32
+ /** What it serves. */
33
+ readonly serves: string;
34
+ }
@@ -5,18 +5,3 @@ export async function route(ctx, routes) {
5
5
  return true;
6
6
  return false;
7
7
  }
8
- /**
9
- * Every dispatcher: a module that takes a request from a socket (or a host's
10
- * server) and holds it to the door before any route reads it, in the door's
11
- * order — the Host, the proxy's identity, the product's session, then a
12
- * write's Origin and body. test/door.test.ts stands each up and sends it the
13
- * same refusals; a new one is named here, and given a row there.
14
- */
15
- export const DISPATCHERS = [
16
- { module: 'packages/tablewalk/src/server/http/browserHandler.ts', serves: 'the database browser' },
17
- { module: 'packages/mistri/src/server/http/handler.ts', serves: 'the Apps of a deployment that serves them' },
18
- { module: 'packages/mistri/src/server/embed/handler.ts', serves: 'an App mounted inside somebody else’s server' },
19
- { module: 'packages/mistri/src/server/http/suite.ts', serves: 'several deployments under one origin, each behind its own dispatcher' },
20
- { module: 'packages/mistri/src/server/tenant/tenantAuthenticatedHttp.ts', serves: 'a tenant App’s browser host and its native sign-in' },
21
- { module: 'packages/mistri/src/server/tenant/tenantHttp.ts', serves: 'a tenant App’s data, inside its browser host' },
22
- ];
@@ -3,13 +3,60 @@ import { type Options } from '../cli/args.js';
3
3
  import { type StartupConfig } from '../cli/config.js';
4
4
  import type { ConfigSections } from '../configSections.js';
5
5
  import { type TargetBinding } from './target.js';
6
- /** What a run keeps of the App `--app` names: what it binds, and its two questions after a run. */
6
+ import { contextLines } from '../config/profile.js';
7
+ /**
8
+ * One phase of the bootstrap plan (docs/bootstrap-plan.md): what `migrate status --app` reports and `migrate up --app`
9
+ * carries out, in order: migrations, stores, sign-in store, seed, check. One word for where it stands, one line
10
+ * beside it, and the names under it.
11
+ */
12
+ export interface PlanPhase {
13
+ readonly phase: 'migrations' | 'stores' | 'sign-in store' | 'seed' | 'check';
14
+ /**
15
+ * `done` was in place before this run; `applied` this run changed it; `pending` up would change it; `waiting` an
16
+ * earlier phase is pending or failed; `failed` it was run and did not finish; `skipped` it cannot be run here, for
17
+ * the reason beside it; `passed` the check judged the App and it fits; `at start` the first start makes it;
18
+ * `—` reported, never run (seed), or nothing to do.
19
+ */
20
+ readonly status: 'done' | 'applied' | 'pending' | 'waiting' | 'failed' | 'skipped' | 'passed' | 'at start' | '—';
21
+ readonly detail: string;
22
+ readonly items: readonly string[];
23
+ readonly error?: string;
24
+ }
25
+ /** What the App framework hands the plan for the phases after the migrations (cli/appTargets.ts). */
26
+ export interface BootstrapInput {
27
+ /** `plan`: read and say (status, validate, a dry run). `up`: carry out what is pending. */
28
+ readonly mode: 'plan' | 'up';
29
+ /** Where phase 1 stands: the stores wait on it when it is pending or failed. */
30
+ readonly migrations: PlanPhase;
31
+ readonly registry: Registry;
32
+ /** The database the migrations ran on. */
33
+ readonly target: Readonly<{
34
+ url: string;
35
+ dialect: string;
36
+ schemas: readonly string[];
37
+ }>;
38
+ /** The start's flags this run was given (`--config`, `--commands`, `--jobs`, `--policy`…), which the check is given too. */
39
+ readonly rest: readonly string[];
40
+ readonly opts: Options;
41
+ /** Where a phase's own output goes (the check's findings, the stores step's lines). */
42
+ readonly write: (line: string) => void;
43
+ }
44
+ /** What a run keeps of the App `--app` names: what it binds, its types, and the phases after the migrations. */
7
45
  export interface MigrateApp {
8
46
  readonly binding: TargetBinding;
9
47
  /** `status`: say when the App's generated types are older than the database. */
10
48
  types(registry: Registry, write: (line: string) => void): Promise<void>;
11
- /** After `up`: the App judged against the schema the run left, its problems written; false when it no longer fits. */
12
- check(rest: string[], write: (line: string) => void): Promise<boolean>;
49
+ /**
50
+ * The phases after the migrations, planned or carried out: the stores this App uses, its sign-in store, a word on
51
+ * seed data, and the check. `title` names the App; `next` is the `migrate up --app …` that applies what is pending.
52
+ */
53
+ bootstrap(input: BootstrapInput): Promise<{
54
+ title: string;
55
+ next: string;
56
+ phases: PlanPhase[];
57
+ }>;
58
+ /** The entries the App says itself (its commands.ts, a build's bundles), for the context the plan prints. */
59
+ readonly entries?: Parameters<typeof contextLines>[1];
13
60
  }
14
61
  /** What a host's command is handed: the database read the way a start reads it, and the App when one was named. */
15
62
  interface MigrateCommandInput<A extends MigrateApp> {