@runeditrun/rer 0.2.110 → 0.2.112

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 (68) hide show
  1. package/README.md +39 -2
  2. package/cli/README.md +56 -0
  3. package/cli/agent-door.mjs +12 -45
  4. package/cli/agent-history-database.mjs +13 -6
  5. package/cli/bounded.mjs +3 -3
  6. package/cli/contract.mjs +5 -1
  7. package/cli/deploy-command.mjs +4 -2
  8. package/cli/deploy-policy.mjs +17 -0
  9. package/cli/hosted-output.mjs +30 -10
  10. package/cli/hosted-owner.mjs +85 -0
  11. package/cli/inspect.mjs +6 -2
  12. package/cli/lifecycle.mjs +5 -1
  13. package/cli/main.mjs +13 -0
  14. package/cli/parse.mjs +4 -4
  15. package/cli/portability.mjs +3 -3
  16. package/cli/size/build-facts.mjs +58 -0
  17. package/cli/size/build-paths.mjs +3 -0
  18. package/cli/size/check.mjs +16 -0
  19. package/cli/size/clauses.mjs +21 -0
  20. package/cli/size/clock.mjs +21 -0
  21. package/cli/size/command.mjs +64 -0
  22. package/cli/size/declaration.mjs +87 -0
  23. package/cli/size/dml-parts.mjs +108 -0
  24. package/cli/size/examples/happytohelp.json +68 -0
  25. package/cli/size/expression-depth.mjs +45 -0
  26. package/cli/size/expression.mjs +33 -0
  27. package/cli/size/fixture.mjs +139 -0
  28. package/cli/size/flows.mjs +81 -0
  29. package/cli/size/from-items.mjs +124 -0
  30. package/cli/size/grow.mjs +83 -0
  31. package/cli/size/install.mjs +136 -0
  32. package/cli/size/json-duplicates.mjs +45 -0
  33. package/cli/size/limits.mjs +9 -0
  34. package/cli/size/measure.mjs +9 -0
  35. package/cli/size/meter.mjs +167 -0
  36. package/cli/size/personas.mjs +138 -0
  37. package/cli/size/report.mjs +23 -0
  38. package/cli/size/schema-objects.mjs +80 -0
  39. package/cli/size/schema.mjs +56 -0
  40. package/cli/size/statements.mjs +53 -0
  41. package/cli/size/validate-flows.mjs +109 -0
  42. package/cli/size/validate-kit.mjs +44 -0
  43. package/cli/size/validate-shape.mjs +75 -0
  44. package/cli/size/verdict.mjs +131 -0
  45. package/cli/size/verify-step.mjs +35 -0
  46. package/global/CHANGELOG.md +50 -0
  47. package/global/README.md +39 -2
  48. package/global/cli/install.mjs +1 -1
  49. package/global/main.mjs +3 -0
  50. package/global/run.mjs +15 -2
  51. package/install.sh +3 -0
  52. package/modules/agent-door/conformance/audit.mjs +3 -0
  53. package/modules/d1-transport/limits.mjs +5 -1
  54. package/modules/deploy-kit/sql-tokens.mjs +5 -4
  55. package/modules/operator-auth/accounts/one-click.mjs +2 -0
  56. package/modules/operator-auth/dev/index.mjs +7 -1
  57. package/modules/operator-auth/dev/invited.mjs +11 -0
  58. package/modules/operator-auth/dev-gate.mjs +3 -2
  59. package/modules/operator-auth/routes.mjs +4 -0
  60. package/modules/portability/progress.mjs +12 -10
  61. package/modules/release/README.md +8 -0
  62. package/modules/release/archive-guard.mjs +22 -0
  63. package/modules/release/archive-members.mjs +49 -0
  64. package/modules/release/export.mjs +7 -1
  65. package/onboarding/commands.mjs +17 -8
  66. package/onboarding/migration-progress.mjs +69 -0
  67. package/onboarding/operator-migrations.mjs +1 -0
  68. package/package.json +2 -1
@@ -0,0 +1,109 @@
1
+ import { count, integer, isInt, isObject, keyed, methods, name as personaName, slug, stringsIn, templateRefs, variable } from './validate-kit.mjs';
2
+
3
+ const pointer = /^(?:\/(?:[^~/]|~[01])*)+$/;
4
+
5
+ // Template problems in `texts`. `own` is the variable set a {{var}} may use (inside a persona); without it only
6
+ // {{persona.var}} is allowed (inside a flow) and `personas` maps each persona to its captured variables.
7
+ function templates(found, texts, path, { own, personas }) {
8
+ for (const text of texts) for (const ref of templateRefs(text)) {
9
+ if (ref.bad) found.add(path, `${ref.bad} is not a template; write {{var}} inside a persona or {{persona.var}} inside a flow.`);
10
+ else if (own) {
11
+ if (ref.persona) found.add(path, `{{${ref.persona}.${ref.variable}}} names a persona inside a persona's own requests; write {{${ref.variable}}}.`);
12
+ else if (!own.has(ref.variable)) found.add(path, `{{${ref.variable}}} is not captured by an earlier request of this persona; add capture ${ref.variable} to the request that returns it, or correct the name.`);
13
+ } else if (!ref.persona) found.add(path, `{{${ref.variable}}} needs its persona in a flow; write {{persona.${ref.variable}}}.`);
14
+ else if (!personas.has(ref.persona)) found.add(path, `{{${ref.persona}.${ref.variable}}}: persona ${ref.persona} is not declared in personas.`);
15
+ else if (!personas.get(ref.persona).has(ref.variable)) found.add(path, `{{${ref.persona}.${ref.variable}}}: persona ${ref.persona} captures no ${ref.variable}; add capture ${ref.variable} to one of its requests, or correct the name.`);
16
+ }
17
+ }
18
+
19
+ function headers(found, value, path, scope) {
20
+ if (!isObject(value)) { found.add(path, 'must map header names to text, for example { "Authorization": "Bearer {{token}}" }.'); return; }
21
+ for (const [header, text] of Object.entries(value)) {
22
+ if (typeof text !== 'string') found.add([...path, header], 'must be text.');
23
+ else templates(found, [text], [...path, header], scope);
24
+ }
25
+ }
26
+
27
+ function request(found, value, path, scope, { setup }) {
28
+ const allowed = setup ? ['method', 'path', 'body', 'headers', 'capture'] : ['method', 'path', 'body', 'headers', 'websocket'];
29
+ if (!keyed(found, value, path, allowed, setup ? 'a setup request' : 'a request')) return;
30
+ if (!methods.includes(value.method)) found.add([...path, 'method'], `must be one of ${methods.join(', ')}.`);
31
+ if (typeof value.path !== 'string' || !value.path.startsWith('/')) found.add([...path, 'path'], 'must be a route path starting with "/".');
32
+ else templates(found, [value.path], [...path, 'path'], scope);
33
+ if (value.body !== undefined) templates(found, stringsIn(value.body), [...path, 'body'], scope);
34
+ if (value.headers !== undefined) headers(found, value.headers, [...path, 'headers'], scope);
35
+ if (!setup && value.websocket !== undefined && typeof value.websocket !== 'boolean') found.add([...path, 'websocket'], 'must be true or false.');
36
+ }
37
+
38
+ // personas: returns Map persona -> Set of captured variables. Each persona's own templates see earlier captures only.
39
+ export function validatePersonas(found, personas, path) {
40
+ const captured = new Map();
41
+ if (personas === undefined) return captured;
42
+ if (!isObject(personas)) { found.add(path, 'must map a persona name to { "kind": "owner" | "anonymous" | "signin" }.'); return captured; }
43
+ for (const [persona, spec] of Object.entries(personas)) {
44
+ const here = [...path, persona], variables = new Set();
45
+ captured.set(persona, variables);
46
+ if (!personaName.test(persona)) found.add(here, 'is not a persona name (lowercase letters, digits and underscore, starting with a letter).');
47
+ if (!isObject(spec) || !['owner', 'anonymous', 'signin'].includes(spec.kind)) { found.add([...here, 'kind'], 'must be "owner", "anonymous" or "signin".'); continue; }
48
+ if (spec.kind !== 'signin') { keyed(found, spec, here, ['kind'], `a ${spec.kind} persona`); continue; }
49
+ if (!keyed(found, spec, here, ['kind', 'requests', 'headers'], 'a signin persona')) continue;
50
+ if (!Array.isArray(spec.requests) || spec.requests.length < 1 || spec.requests.length > 4) found.add([...here, 'requests'], 'must list 1 to 4 sign-in requests, run in order.');
51
+ else spec.requests.forEach((item, index) => {
52
+ request(found, item, [...here, 'requests', index], { own: new Set(variables) }, { setup: true });
53
+ if (isObject(item) && item.capture !== undefined) {
54
+ if (!isObject(item.capture) || !Object.keys(item.capture).length) found.add([...here, 'requests', index, 'capture'], 'must map a variable name to a JSON pointer into the response, for example { "token": "/token" }.');
55
+ else for (const [key, at] of Object.entries(item.capture)) {
56
+ if (!variable.test(key)) found.add([...here, 'requests', index, 'capture', key], 'is not a variable name.');
57
+ else if (typeof at !== 'string' || !pointer.test(at)) found.add([...here, 'requests', index, 'capture', key], 'must be a JSON pointer such as "/token".');
58
+ else variables.add(key);
59
+ }
60
+ }
61
+ });
62
+ if (spec.headers !== undefined) headers(found, spec.headers, [...here, 'headers'], { own: variables });
63
+ }
64
+ return captured;
65
+ }
66
+
67
+ function growth(found, value, path) {
68
+ if (!keyed(found, value, path, ['allowed', 'why'], 'growth')) return;
69
+ if (value.allowed !== true) found.add([...path, 'allowed'], 'must be true; delete growth to have the flow checked for growth.');
70
+ if (typeof value.why !== 'string' || !value.why.trim()) found.add([...path, 'why'], 'growth.allowed needs a why: say in one sentence why this flow may read more at the large size; it is printed on every run.');
71
+ }
72
+
73
+ function status(found, value, path) {
74
+ const codes = Array.isArray(value) ? value : [value];
75
+ if (!codes.length || !codes.every(code => isInt(code, 100, 599))) found.add(path, 'must be an HTTP status from 100 to 599, or a non-empty list of them.');
76
+ }
77
+
78
+ // flows: returns the normalized list. `facts.crons` are the crons the checkout declares; `budget.windowRows` may be unset.
79
+ export function validateFlows(found, flows, path, { personas, crons, windowRows }) {
80
+ if (!Array.isArray(flows) || flows.length < 1 || flows.length > 64) { found.add(path, 'must list 1 to 64 flows, each with a ceiling.'); return []; }
81
+ const names = new Set(), normalized = [];
82
+ flows.forEach((flow, index) => {
83
+ const label = typeof flow?.name === 'string' && slug.test(flow.name) ? flow.name : index, here = [...path, label];
84
+ const scheduled = isObject(flow) && flow.scheduled !== undefined;
85
+ if (!keyed(found, flow, here, ['name', 'ceiling', 'callsInRow', 'repeat', 'status', 'growth', ...(scheduled ? ['scheduled'] : ['persona', 'request'])], 'a flow')) return;
86
+ if (typeof flow.name !== 'string' || !slug.test(flow.name)) found.add([...here, 'name'], 'must be a short name of lowercase letters, digits and hyphens.');
87
+ else if (names.has(flow.name)) found.add([...here, 'name'], `${flow.name} is used by two flows; give each flow its own name.`);
88
+ else names.add(flow.name);
89
+ if (scheduled) {
90
+ if (typeof flow.scheduled !== 'string' || !flow.scheduled.trim()) found.add([...here, 'scheduled'], 'must be one of the cron expressions the build declares.');
91
+ else if (!crons.includes(flow.scheduled)) found.add([...here, 'scheduled'], `cron "${flow.scheduled}" is not one the checkout declares (${crons.length ? crons.map(cron => `"${cron}"`).join(', ') : 'it declares none'}); name a declared cron, or declare it in triggers.crons.`);
92
+ } else {
93
+ if (typeof flow.persona !== 'string' || !personas.has(flow.persona)) found.add([...here, 'persona'], `${typeof flow.persona === 'string' ? `persona ${flow.persona} is not declared` : 'is required for a request flow'}; declare it under personas${personas.size ? ` (declared: ${[...personas.keys()].join(', ')})` : ''}, or correct the name.`);
94
+ if (flow.request === undefined) found.add([...here, 'request'], 'is required; give method and path, or use "scheduled" for a cron flow.');
95
+ else request(found, flow.request, [...here, 'request'], { personas }, { setup: false });
96
+ }
97
+ const ceiling = integer(found, flow.ceiling, [...here, 'ceiling'], 1, undefined, 'it is the rows this flow may read at the large size, per call');
98
+ const calls = flow.callsInRow === undefined ? true : integer(found, flow.callsInRow, [...here, 'callsInRow'], 1);
99
+ if (ceiling && calls && windowRows) {
100
+ const inRow = flow.callsInRow ?? 1, total = flow.ceiling * inRow;
101
+ if (total > windowRows) found.add([...here, 'ceiling'], `ceiling ${count(flow.ceiling)} x callsInRow ${count(inRow)} = ${count(total)} rows, over budget.windowRows ${count(windowRows)}; lower the ceiling or the calls in a row.`);
102
+ }
103
+ if (flow.repeat !== undefined && ![1, 2, 3].includes(flow.repeat)) found.add([...here, 'repeat'], 'must be 1, 2 or 3.');
104
+ if (flow.status !== undefined) status(found, flow.status, [...here, 'status']);
105
+ if (flow.growth !== undefined) growth(found, flow.growth, [...here, 'growth']);
106
+ normalized.push({ ...flow, callsInRow: flow.callsInRow ?? 1, repeat: flow.repeat ?? 1, status: flow.status === undefined ? null : [].concat(flow.status), growth: flow.growth ?? null });
107
+ });
108
+ return normalized;
109
+ }
@@ -0,0 +1,44 @@
1
+ // Small pieces shared by the size-check.json validators: a problem list keyed by field path, key and number checks,
2
+ // and the {{var}} / {{persona.var}} template scan.
3
+ export const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
4
+ export const isInt = (value, low, high = Infinity) => Number.isInteger(value) && value >= low && value <= high;
5
+ export const count = number => number.toLocaleString('en-US');
6
+ export const identifier = /^[A-Za-z_][A-Za-z0-9_]*$/, slug = /^[a-z0-9][a-z0-9-]{0,63}$/, name = /^[a-z][a-z0-9_]{0,31}$/, variable = /^[A-Za-z_][A-Za-z0-9_]{0,31}$/;
7
+ export const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
8
+
9
+ // Every problem is { path, message }: the path is the dotted field path the clause id carries.
10
+ export function problems() {
11
+ const list = [];
12
+ return { list, add: (path, message) => { list.push({ path: path.join('.'), message }); } };
13
+ }
14
+
15
+ // The value as an object with only the allowed keys; unknown keys are refused by name.
16
+ export function keyed(found, value, path, allowed, label = 'it') {
17
+ if (!isObject(value)) { found.add(path, `must be an object; write { ${allowed.slice(0, 3).join(', ')}, … } (allowed keys: ${allowed.join(', ')}).`); return false; }
18
+ for (const key of Object.keys(value)) if (!allowed.includes(key)) found.add([...path, key], `unknown key "${key}"; remove it or correct the spelling (allowed in ${label}: ${allowed.join(', ')}).`);
19
+ return true;
20
+ }
21
+
22
+ export function integer(found, value, path, low, high, fix) {
23
+ if (isInt(value, low, high)) return true;
24
+ found.add(path, `must be a whole number ${high === undefined || high === Infinity ? `of at least ${count(low)}` : `from ${count(low)} to ${count(high)}`}${fix ? `; ${fix}` : ''}.`);
25
+ return false;
26
+ }
27
+
28
+ export function* stringsIn(value) {
29
+ if (typeof value === 'string') yield value;
30
+ else if (Array.isArray(value)) for (const item of value) yield* stringsIn(item);
31
+ else if (isObject(value)) for (const item of Object.values(value)) yield* stringsIn(item);
32
+ }
33
+
34
+ // Each {{…}} in the text as { persona?, variable } or { bad } when it is neither {{var}} nor {{persona.var}}.
35
+ export function templateRefs(text) {
36
+ return [...text.matchAll(/\{\{([^{}]*)\}\}/g)].map(match => {
37
+ const parts = match[1].trim().split('.');
38
+ if (parts.length === 1 && variable.test(parts[0])) return { variable: parts[0] };
39
+ if (parts.length === 2 && name.test(parts[0]) && variable.test(parts[1])) return { persona: parts[0], variable: parts[1] };
40
+ return { bad: match[0] };
41
+ });
42
+ }
43
+
44
+ export const pathProblem = path => typeof path !== 'string' || !path || path.startsWith('/') || path.includes('\\') || path.includes('\0') || path.split('/').includes('..');
@@ -0,0 +1,75 @@
1
+ import { expressionProblem } from './expression.mjs';
2
+ import { count, identifier, integer, isInt, isObject, keyed } from './validate-kit.mjs';
3
+
4
+ const maxRows = 5_000_000;
5
+
6
+ function rowCounts(found, rows, path) {
7
+ if (isInt(rows, 1, maxRows)) return { small: rows, large: rows };
8
+ if (isObject(rows) && keyed(found, rows, path, ['small', 'large'], 'rows')) {
9
+ const small = integer(found, rows.small, [...path, 'small'], 1, maxRows), large = integer(found, rows.large, [...path, 'large'], 1, maxRows);
10
+ return small && large ? { small: rows.small, large: rows.large } : undefined;
11
+ }
12
+ if (!isObject(rows)) found.add(path, `must be a whole number from 1 to ${count(maxRows)}, or { "small": N, "large": N }.`);
13
+ }
14
+
15
+ function histogram(found, spec, path, rows) {
16
+ if (!isObject(spec) || !Object.keys(spec).length) { found.add(path, 'must map children per parent to the number of parents, for example { "3": 10, "1": 40 }.'); return; }
17
+ let total = 0;
18
+ for (const [children, parents] of Object.entries(spec)) {
19
+ if (!/^[1-9][0-9]*$/.test(children) || !isInt(parents, 1)) { found.add(path, `entry "${children}": ${JSON.stringify(parents)} must be children per parent (a whole number of at least 1) mapped to a parent count of at least 1.`); return; }
20
+ total += Number(children) * parents;
21
+ }
22
+ const wanted = rows ? [...new Set([rows.small, rows.large])] : [];
23
+ if (wanted.some(number => number !== total)) found.add(path, `children x parents sums to ${count(total)} but rows is ${wanted.map(count).join(' and ')}; make the histogram sum equal rows, or change rows.`);
24
+ return total;
25
+ }
26
+
27
+ function parentOf(found, parent, path, earlier, rows) {
28
+ const spec = isObject(parent) && 'histogram' in parent ? ['table', 'histogram'] : ['table', 'per'];
29
+ if (!keyed(found, parent, path, spec, 'parent')) return;
30
+ if (typeof parent.table !== 'string' || !identifier.test(parent.table)) found.add([...path, 'table'], 'must name the parent table.');
31
+ else if (!earlier.includes(parent.table)) found.add([...path, 'table'], `${parent.table} must be listed earlier in shape.tables than the table that belongs to it; move ${parent.table} up, or correct the name.`);
32
+ if ('histogram' in parent) histogram(found, parent.histogram, [...path, 'histogram'], rows);
33
+ else integer(found, parent.per, [...path, 'per'], 1, undefined, 'per is the number of children each parent row gets');
34
+ }
35
+
36
+ function sql(found, value, path) {
37
+ const problem = expressionProblem(value);
38
+ if (problem) found.add(path, `${problem}.`);
39
+ }
40
+
41
+ function values(found, spec, path) {
42
+ if (!isObject(spec) || !Object.keys(spec).length) { found.add(path, 'must map each column to a SQLite expression, for example { "id": "printf(\'c%06d\', n)" }.'); return; }
43
+ for (const [column, expression] of Object.entries(spec)) {
44
+ if (!identifier.test(column)) { found.add([...path, column], 'is not a column name (letters, digits and underscore).'); continue; }
45
+ if (isObject(expression)) {
46
+ if (!keyed(found, expression, [...path, column], ['jsonArray'], 'a column value')) continue;
47
+ if (keyed(found, expression.jsonArray, [...path, column, 'jsonArray'], ['length', 'item'], 'jsonArray')) {
48
+ sql(found, expression.jsonArray.length, [...path, column, 'jsonArray', 'length']);
49
+ sql(found, expression.jsonArray.item, [...path, column, 'jsonArray', 'item']);
50
+ }
51
+ } else sql(found, expression, [...path, column]);
52
+ }
53
+ }
54
+
55
+ // shape: { tables, after }. Returns the normalized shape, or undefined when it has problems.
56
+ export function validateShape(found, shape, path) {
57
+ if (!keyed(found, shape, path, ['tables', 'after'], 'shape')) return;
58
+ const tables = shape.tables, after = shape.after ?? [], normalized = { tables: [], after: [] }, before = found.list.length;
59
+ if (!Array.isArray(tables) || tables.length < 1 || tables.length > 64) found.add([...path, 'tables'], 'must list 1 to 64 tables, each with its rows and column values.');
60
+ else tables.forEach((table, index) => {
61
+ const here = [...path, 'tables', typeof table?.table === 'string' && identifier.test(table.table) ? table.table : index];
62
+ if (!keyed(found, table, here, ['table', 'rows', 'chunk', 'parent', 'values'], 'a table')) return;
63
+ if (typeof table.table !== 'string' || !identifier.test(table.table)) found.add([...here, 'table'], 'must be the table name (letters, digits and underscore).');
64
+ const rows = table.rows === undefined ? (found.add([...here, 'rows'], 'is required; give the row count or { "small": N, "large": N }.'), undefined) : rowCounts(found, table.rows, [...here, 'rows']);
65
+ if (table.chunk !== undefined) integer(found, table.chunk, [...here, 'chunk'], 100, 50_000);
66
+ if (table.parent !== undefined) parentOf(found, table.parent, [...here, 'parent'], tables.slice(0, index).map(earlier => earlier?.table), rows);
67
+ if (table.values === undefined) found.add([...here, 'values'], 'is required; map each column to a SQLite expression.');
68
+ else values(found, table.values, [...here, 'values']);
69
+ normalized.tables.push({ ...table, rows: rows ?? table.rows, chunk: table.chunk ?? 10_000 });
70
+ });
71
+ if (!Array.isArray(after) || after.length > 16) found.add([...path, 'after'], 'must list at most 16 single statements.');
72
+ else after.forEach((statement, index) => sql(found, statement, [...path, 'after', index]));
73
+ normalized.after = after;
74
+ return found.list.length === before ? normalized : undefined;
75
+ }
@@ -0,0 +1,131 @@
1
+ import { d1Limits, failAt, SIZE_MARGIN } from './limits.mjs';
2
+ import { measureStatements } from './statements.mjs';
3
+
4
+ // What the metered flows add up to. A flow fails when, at either size or between them:
5
+ // ceiling it read more rows at large than its ceiling;
6
+ // growth it read more at large than at small by over growthPercent of small plus growthRows
7
+ // (unless growth.allowed, whose why is printed on every run);
8
+ // status it answered another status than declared (any 2xx or 3xx, and 101 for a websocket);
9
+ // refused local D1 refused or failed a statement it ran;
10
+ // statement-size a distinct statement it ran is at 90 or more FROM items or depth.
11
+
12
+ const count = number => number.toLocaleString('en-US');
13
+ const preview = sql => sql.replace(/\s+/g, ' ').trim().slice(0, 160);
14
+ const sizes = ['small', 'large'];
15
+
16
+ /** The statements of `executions` that read the most rows, summed by text: [{ binding, sql, executions, rowsRead, rowsWritten }]. */
17
+ export function topStatements(executions, limit = 3) {
18
+ const groups = new Map();
19
+ for (const { binding, sql, rows_read, rows_written } of executions) {
20
+ const key = `${binding}\0${sql}`, group = groups.get(key) ?? { binding, sql, executions: 0, rowsRead: 0, rowsWritten: 0 };
21
+ group.executions++;
22
+ group.rowsRead += rows_read;
23
+ group.rowsWritten += rows_written;
24
+ groups.set(key, group);
25
+ }
26
+ return [...groups.values()].sort((a, b) => b.rowsRead - a.rowsRead).slice(0, limit);
27
+ }
28
+
29
+ // Every distinct statement text the flows ran (exec text can hold several statements and has no row meta, so it is
30
+ // not measured), measured against the schema of its own D1 binding: Map(binding -> Map(sql -> record)).
31
+ function measureDistinct(schemas, flowResults) {
32
+ const texts = new Map();
33
+ for (const result of flowResults) for (const { binding, sql, exec } of result.executions) if (!exec) texts.set(binding, (texts.get(binding) ?? new Set()).add(sql));
34
+ const measured = new Map();
35
+ for (const [binding, sqls] of texts) {
36
+ const schema = schemas.find(item => item.binding === binding);
37
+ if (!schema) continue;
38
+ const list = [...sqls], records = measureStatements(schema.db, list.map((sql, index) => ({ name: `statement ${index}`, sql })));
39
+ measured.set(binding, new Map(list.map((sql, index) => [sql, records[index]])));
40
+ }
41
+ return measured;
42
+ }
43
+
44
+ const summary = run => ({ rowsRead: run.rowsRead, rowsWritten: run.rowsWritten, statements: run.statements, status: run.status, ms: Math.round(run.ms), ...(run.error ? { error: run.error } : {}), ...(run.detail ? { detail: run.detail } : {}), ...(run.unsettled ? { unsettled: true } : {}), top: topStatements(run.executions) });
45
+
46
+ // Only the measures at the failing line: a statement at depth 105 says so and not "0 FROM items".
47
+ function sizeText({ fromItems, depth }) {
48
+ const parts = [];
49
+ if (fromItems >= failAt.fromItems) parts.push(`${fromItems} FROM items after expanding CTEs and views`);
50
+ if ((depth ?? Infinity) >= failAt.depth) parts.push(`expression depth ${depth ?? 'over the limit'}`);
51
+ return `${parts.join(', ')} (rer fails at ${failAt.fromItems} FROM items or depth ${failAt.depth}; D1 refuses at ${d1Limits.fromItems} and ${d1Limits.depth})`;
52
+ }
53
+
54
+ function statusProblem(flow, run) {
55
+ const expected = flow.status ?? (flow.scheduled === undefined ? flow.request.websocket ? [101] : null : ['ok']);
56
+ const wanted = expected === null ? 'a 2xx or 3xx status' : `status ${expected.join(' or ')}`;
57
+ if (run.error) return `${flow.scheduled === undefined ? 'its request' : 'the scheduled handler'} failed: ${run.error}`;
58
+ const ok = expected === null ? run.status >= 200 && run.status < 400 : expected.includes(run.status);
59
+ if (ok) return null;
60
+ return flow.scheduled === undefined ? `answered HTTP ${run.status}${run.detail ? ` (${run.detail})` : ''}; expected ${wanted}` : `the scheduled handler did not finish (${run.status}); expected it to run to the end`;
61
+ }
62
+
63
+ /**
64
+ * Judges every declared flow. `small` and `large` are the runFlows results of each size, in declared order;
65
+ * `schemas` are the build's D1 schemas ({ binding, db }, see schemasFromBuild) the statements are measured against.
66
+ * Resolves { ok, flows: [{ name, persona, kind, label, ok, failures: [{ rule, message }], growthAllowed, small, large }], checked }.
67
+ */
68
+ export function judgeFlows(declaration, small, large, schemas) {
69
+ const { growthPercent, growthRows } = declaration.budget;
70
+ const measured = measureDistinct(schemas, [...small, ...large]);
71
+ const verdicts = declaration.flows.map((flow, index) => {
72
+ const at = { small: small[index], large: large[index] }, failures = [];
73
+ const wrong = new Map();
74
+ for (const size of sizes) { const problem = statusProblem(flow, at[size]); if (problem) wrong.set(problem, [...wrong.get(problem) ?? [], size]); }
75
+ for (const [problem, where] of wrong) failures.push({ rule: 'status', message: `${problem} at ${where.join(' and ')}` });
76
+ const refused = new Map();
77
+ for (const size of sizes) for (const { sql, error } of at[size].executions) if (error) {
78
+ const key = `${sql}\0${error}`;
79
+ refused.set(key, { sql, error, sizes: [...refused.get(key)?.sizes ?? [], size] });
80
+ }
81
+ for (const { sql, error, sizes: where } of refused.values()) failures.push({ rule: 'refused', message: `local D1 refused or failed a statement at ${where.join(' and ')}: ${error.replace(/^D1_ERROR:\s*/, '').replace(/:\s*SQLITE_\w+(?: \(extended: \w+\))?\s*$/, '')}`, sql });
82
+ const rows = { small: at.small.rowsRead, large: at.large.rowsRead };
83
+ if (rows.large > flow.ceiling) failures.push({ rule: 'ceiling', message: `over its ceiling of ${count(flow.ceiling)} at large by ${count(rows.large - flow.ceiling)}${flow.callsInRow > 1 ? ` (${flow.callsInRow} calls in a row)` : ''}` });
84
+ const allowed = Math.floor(growthPercent / 100 * rows.small + growthRows);
85
+ if (rows.large - rows.small > growthPercent / 100 * rows.small + growthRows && !flow.growth) failures.push({ rule: 'growth', message: `grew ${count(rows.large - rows.small)} rows from small to large; allowed ${growthPercent}% of small + ${count(growthRows)} = ${count(allowed)}` });
86
+ const seen = new Set();
87
+ for (const size of sizes) for (const { binding, sql, exec } of at[size].executions) {
88
+ if (exec || seen.has(`${binding}\0${sql}`)) continue;
89
+ seen.add(`${binding}\0${sql}`);
90
+ const record = measured.get(binding)?.get(sql);
91
+ if (!record || record.ok) continue;
92
+ failures.push({ rule: 'statement-size', message: `statement size: ${record.error ?? sizeText(record)}`, sql, ...(record.error ? {} : { fromItems: record.fromItems, depth: record.depth }) });
93
+ }
94
+ return { name: flow.name, persona: flow.persona ?? null, kind: at.small.kind, label: at.small.label, callsInRow: flow.callsInRow, ceiling: flow.ceiling, ok: failures.length === 0, failures, growthAllowed: flow.growth?.why ?? null, small: summary(at.small), large: summary(at.large) };
95
+ });
96
+ const checked = [...measured.values()].reduce((all, records) => all + records.size, 0);
97
+ return { ok: verdicts.every(verdict => verdict.ok), flows: verdicts, checked };
98
+ }
99
+
100
+ /** The lines a person reads: one per flow, each failure's reasons and its three heaviest statements at large, then
101
+ * a summary. */
102
+ export function verdictLines(verdict, declaration) {
103
+ const lines = [], widths = { name: 0, persona: 0, label: 0 };
104
+ for (const flow of verdict.flows) for (const key of Object.keys(widths)) widths[key] = Math.max(widths[key], String(flow[key] ?? '').length);
105
+ for (const flow of verdict.flows) {
106
+ const status = flow.large.status ?? 'no response', extra = flow.large.unsettled ? '; work still running after 30 s is not counted' : '';
107
+ lines.push(` ${flow.ok ? 'ok ' : 'FAIL'} ${flow.name.padEnd(widths.name)} ${String(flow.persona ?? '').padEnd(widths.persona)} ${flow.label.padEnd(widths.label)} ${count(flow.small.rowsRead)} → ${count(flow.large.rowsRead)} rows, ${count(flow.large.statements)} statement${flow.large.statements === 1 ? '' : 's'}, ${status}${extra}`);
108
+ if (flow.growthAllowed) lines.push(` growth allowed: ${flow.growthAllowed}`);
109
+ if (flow.ok) continue;
110
+ for (const failure of flow.failures) {
111
+ lines.push(` ${failure.message}`);
112
+ if (failure.sql) lines.push(` ${preview(failure.sql)}`);
113
+ }
114
+ for (const top of flow.large.top.filter(top => top.rowsRead > 0)) lines.push(` ${count(top.rowsRead)} rows x${count(top.executions)} ${preview(top.sql)}`);
115
+ }
116
+ const failing = verdict.flows.filter(flow => !flow.ok).length;
117
+ lines.push(` ${failing ? `${failing} of ${verdict.flows.length} flows fail` : `All ${verdict.flows.length} flows pass`}; ${count(verdict.checked)} distinct statements checked for size. Rows are local D1's own count.`);
118
+ if (failing) lines.push(` Real D1 also refuses at ${d1Limits.fromItems} FROM items (rer fails at ${failAt.fromItems}, a margin of ${SIZE_MARGIN}) and budgets a database's reads in a 10-second window (here ceiling x calls in a row must stay under ${count(declaration.budget.windowRows)}). Confirm a fix on real D1 before relying on it.`);
119
+ return lines;
120
+ }
121
+
122
+ /** One size's statements in the fleet runner's format: { statements: [{ name: "<flow> #<i>", sql, params }] }, every
123
+ * statement each flow's last run executed, in order, with its parameters as bound. */
124
+ export function statementsFile(size, results) {
125
+ const statements = [];
126
+ for (const result of results) {
127
+ let index = 0;
128
+ for (const { sql, params, exec } of result.executions) if (!exec) statements.push({ name: `${result.name} #${++index}`, sql, params });
129
+ }
130
+ return { about: `rer size: every statement each flow ran at the ${size} size, in order, with its parameters as bound.`, statements };
131
+ }
@@ -0,0 +1,35 @@
1
+ import '../sqlite-notice.mjs';
2
+ import { realpath } from 'node:fs/promises';
3
+ import { resolve } from 'node:path';
4
+ import { RerError } from '../errors.mjs';
5
+ import { measureSize } from './command.mjs';
6
+
7
+ const join = names => names.join(', ');
8
+
9
+ // What failed, by name, for the error that fails verify. The lines that explain it were already reported as they ran.
10
+ function failureText({ statements, size = {}, flows = [] }) {
11
+ const parts = [];
12
+ const refused = statements.filter(statement => !statement.ok);
13
+ if (refused.length) parts.push(`D1 would refuse the build's schema objects ${join(refused.map(statement => statement.name))}`);
14
+ for (const name of ['small', 'large']) if (size[name]?.error) parts.push(`the ${name} size did not build: ${size[name].error}`);
15
+ const failing = flows.filter(flow => !flow.ok);
16
+ if (failing.length) parts.push(`${failing.length} of ${flows.length} declared flows fail: ${join(failing.map(flow => `${flow.name} (${[...new Set(flow.failures.map(failure => failure.rule))].join(', ')})`))}`);
17
+ return `Size check failed: ${parts.join('; ')}. Run rer size for the full report.`;
18
+ }
19
+
20
+ /**
21
+ * The last step of rer verify: `rer size`, in verify's own job-queue slot. Every view and trigger statement of each D1
22
+ * binding's migrations is measured; with a size-check.json at the checkout root the declared shape is also built at a
23
+ * small and a large size and every declared flow run on each. A failure fails verify, naming the statement or the flow.
24
+ * Resolves what `rer size --json` carries, so verify's result carries it as `size`.
25
+ */
26
+ export async function checkSizeStep(root, { report = () => {} } = {}) {
27
+ const { ok, details } = await measureSize({ cwd: root, json: false }, { human: report });
28
+ if (!ok) throw new RerError('size_check_failed', failureText(details), 1);
29
+ return details;
30
+ }
31
+
32
+ if (process.argv[1] && await realpath(new URL(import.meta.url)) === await realpath(process.argv[1])) {
33
+ try { console.log(JSON.stringify(await checkSizeStep(resolve(process.argv[2] ?? '.'), { report: line => console.error(line) }))); }
34
+ catch (error) { console.error(error.message); process.exitCode = 1; }
35
+ }
@@ -1,5 +1,55 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.112
4
+
5
+ ### Downloaded tools and export progress
6
+
7
+ - `rer run --script FILE [ARGS...]` runs a downloaded JavaScript file with the Node running rer, including the installer's private Node, outside a project checkout and without `node` or pnpm on PATH. It preserves the working folder, arguments and exit status; `--cwd DIR` before `--script` selects the folder. Package scripts (`rer run NAME`) continue to use the checkout's pinned runtime. The installer and local instructions show this door; it becomes available when the installed rer is upgraded.
8
+ - Local installation export labels allocated disk space separately from archive size and leaves building time indeterminate until the total work is known. It no longer forecasts archive size or building time from unused database pages and temporary state; known-total writing and staging phases retain their progress estimates. CLI progress only; the archive format is unchanged.
9
+
10
+ ### Setup, import and export migration output
11
+
12
+ - `wrangler d1 migrations apply` run through rer's command runner, including a seed's setup, import or export adapter, shows `Applying migrations N/M` every ten migrations, warnings and errors, and one `Applied N migrations. Full output: <log>` summary. Repeated tables and boilerplate stay in the full log. A failed migration names itself and keeps wrangler's error and log path; an error without a failed row is associated with the first listed migration that did not finish. Shared local import and export now show this progress instead of silencing the whole apply.
13
+ - A finished `rer setup` adds a result line before `RER_SETUP_READY`: the number of migrations applied (or that the database is already up to date), owner setup and the full-output log path. Seeds get these command-runner and setup changes after adopting this rer through their pinned CLI.
14
+
15
+ ### Optional seed deploy policy
16
+
17
+ - Application `rer deploy` awaits optional `commandAdapter.deployPolicy({ root, options, environment, env, bindings, declaration, declarationPath })` once after basic CLI-option and declaration checks, before downstream deploy validation, builds, custom deploy hooks or owner-account provider contact, including secret-only updates and receipt recovery. `env` carries effective proposed local inputs; `bindings` overlays declaration vars with nonblank secrets mapped from their declared environment names, so an ambient binding-name value cannot override an explicit mapping. These are proposed inputs, not hosted secret readback.
18
+ - The hook is local validation: inputs are read-only, its return value is ignored, and it must make no provider calls, builds, settings writes or secret output. A seed can reject applicable operations with `missing(message)` from the same rer copy/package (exit 3, `missing_input`); `refuse(message)` retains exit 4. Seeds without the hook keep their existing deployment checks. This releases CLI support only: each seed must adopt the CLI and implement its own policy, including normalization of its provider choices and aliases. No seed-specific mail policy is inferred, and this release establishes no installed mail-OFF or deployed behavior.
19
+
20
+ Code and documentation only: the actual diff adds no migration. Nothing here establishes seed adoption or changes a deployed seed; each seed must adopt and deploy its own changes.
21
+
22
+ ## 0.2.111
23
+
24
+ ### `rer size`: statement size and growth with data
25
+
26
+ - New `rer size`, and a last step of `rer verify`: statement size against D1's limits. D1 refuses a statement at 100 FROM items (counted with every CTE and view reference expanded in place) or expression depth 100, and local SQLite and Miniflare accept both; rer fails a statement at 90 of either. `rer size` checks the build's view and trigger statements, `--migrations DIR` another schema, and `--statements FILE` a statements file in the fleet runner's format. A seed gets it, and its `rer verify` gets the new last step, only after it adopts this rer (`rer size` runs through the seed's pinned rer); a seed whose views or triggers already sit at 90 FROM items or depth will see its verify fail at that step once it adopts.
27
+ - `rer check` validates a seed's optional `size-check.json` (its table shape, personas, flows and per-flow row ceilings) as `SC-15.size.*` clauses, offline, with no build: unknown keys, undeclared personas and crons, histogram sums, parent order, expressions with a `;`, `growth.allowed` without a `why`, and a ceiling times calls in a row over `budget.windowRows` each fail naming the field and the fix. With no file it passes `SC-15.size.undeclared`.
28
+ - `rer size` with a `size-check.json` (or `--declaration FILE`) builds the declared shape at a small and a large size, each in its own disposable local D1 install served as the hosted check serves the build: the owner is signed in with agent-door's bootstrap (that code moved unchanged into a shared file, `cli/hosted-owner.mjs`), each table is generated inside D1 by chunked `INSERT … SELECT` so the schema's own triggers fire, and each declared table is read back with the time per phase. A generation error names the size, table, row range, SQLite's message and column; `budget.timeoutSeconds` bounds the run and a timeout names the phase; it takes verify's job-queue slot. `@runeditrun/rer/size-fixture` exports the compiler so a fleet runner seeds the same statements.
29
+ - `rer size` then runs every declared flow at the small and the large size through a rows-read meter wrapped around the Worker's D1 bindings (fetch, scheduled, queue, Durable Objects and `waitUntil` work; queues are held and queue consumer work is not measured), as the owner, an anonymous visitor or a persona that signs in with a cookie jar and captured values, and fails a flow that passes its ceiling, reads more at large than at small by over 10 percent plus 200 rows, answers the wrong status, has a statement refused by local D1, or runs a statement at 90 FROM items or depth; `--write-statements DIR` writes the statements each size ran in the fleet runner's format. The meter is served only by `rer size`: nothing changes for the hosted check or agent-door conformance.
30
+ - `rer verify` now ends with the full size check: with a `size-check.json` the last step runs `rer size`'s code inside verify's own job-queue slot, builds the declared shape at a small and a large size, runs every declared flow and fails verify exactly when `rer size` fails, naming each failing flow (the result's `size` carries what `rer size --json` carries); without one it checks the schema objects and prints `Size check: undeclared (no size-check.json).` In a checkout without a seedContract, `rer size` runs from `size-check.json` `build.wrangler` and `build.deployDeclaration` (they now name the built wrangler file and the deploy declaration; the Worker, migrations and assets are read from the wrangler file's folder), allows the owner persona only where `rer-setup.json` has an owner-claim step or `agent-surface.json` has `verification.owner`, and never forwards to a declared argv.
31
+ - The growth check needs a declaration. A seed that declares no `size-check.json` is never asked to grow data: it sees `undeclared`. The HappyToHelp example in `cli/size/examples/happytohelp.json` is a snapshot of that seed's measured shape (11 Nov 2026) and must be refreshed against current measurements before any gate on it is turned on. Verification tooling only: no migration is added.
32
+
33
+ ### Local sign-in and one-click follow-ups
34
+
35
+ - A local run's `/__dev/key` guidance page now names `rer dev --as` followed by an invited person's email only when the app has someone beyond the owner and its dev personas (an active person or one with a live invitation) for it to take; the page still carries no key or address. Wording only; local runs only.
36
+ - A browser that follows a refused local one-click sign-in link (`Accept: text/html`) now reads a short plain-words line (open the link from the app, or run `rer dev --as` with the email) instead of `{"error":"not_found"}`; the status, headers and JSON for any other caller are unchanged. Local runs only.
37
+ - The default seed's operator access panel shows the "can sign in on this computer … `rer dev --as`" invitation text only when served from a local address; elsewhere an invitation that sent no email reads "Saved. No email was sent." Wording only.
38
+
39
+ ### Deploy message
40
+
41
+ - `rer deploy` with a hook that keeps a kit record now shows the cause, the step and the recovery sentence when its pre-hook settle is refused (for example `owner-state-locked` or `secret-change-unsettled`) instead of "Checking pinned pnpm failed"; the settle still stops the deploy before the hook, and the failure ends with exit code 1, the code the kit's other deploy failures already use.
42
+
43
+ ### Agent door: `policy.adopted` metadata
44
+
45
+ - The agent door's `policy.adopted` event now also carries `classes` (the classes the adopted policy has a rule for, as `{ class }` entries like `approval.pending`'s) and `decision` (`{ revision, document_sha256 }`, the adopted revision; digest `null` when no policy document is adopted), so `BASE-AGENT-010` acceptance 6 can be judged; the conformance audit checks the newest adoption for that shape. `seq`, `revision` and the event `uri` are unchanged, nothing else is added (no rule, reviewer, approver, threshold or spend value), and an older subscriber that ignores the new fields keeps working. Additive event fields; a seed's conformance audit checks the shape only after it adopts this release.
46
+
47
+ ### `rer release` archives
48
+
49
+ - `rer release` run on macOS no longer puts `._*` AppleDouble entries (one per file and directory, from extended attributes such as `com.apple.provenance`) into `public-source.tar`, and the release stops with a message if such an entry that is not a tracked path ever reaches the archive; a tracked file whose name starts with `._` is still archived. This changes only archives cut after a checkout adopts this release: no already published release archive is re-cut. No change to the statement or signing format, and archives built on Linux are unchanged.
50
+
51
+ All of the above is code and docs only: no migration is added. A seed gets it by adopting 0.2.111; nothing here is live in any deployed seed until that seed adopts and deploys it.
52
+
3
53
  ## 0.2.110
4
54
 
5
55
  ### Business roster: a teammate erased before adoption stays erased
package/global/README.md CHANGED
@@ -5,7 +5,7 @@ Allow roughly 500 MB–1 GB of downloads and 1–3 GB of disk space for a first
5
5
  <!-- END COLD RUN BUDGET -->
6
6
 
7
7
  `rer` is the Run Edit Run command. Install it once, then run `rer <verb>` in any
8
- Run Edit Run checkout: every verb runs that checkout's own pinned copy, so a
8
+ Run Edit Run checkout: project verbs run that checkout's own pinned copy, so a
9
9
  checkout always gets the behaviour it was built and tested with.
10
10
 
11
11
  For source authors, `rer adopt-edition` adds a recipe and lock to existing tracked
@@ -47,7 +47,20 @@ changing PATH: a child installer cannot change its parent shell’s PATH, and ba
47
47
  `~/.local/bin`, its closing lines give one required step: the
48
48
  `export PATH="$HOME/.local/bin:$PATH"` line to run now and add to your shell
49
49
  startup file, or `rer cli path` (by its absolute launcher) for other shells.
50
- The same start also fits on one line:
50
+ To run a downloaded JavaScript tool, open its folder in the terminal and use
51
+ `"$HOME/.local/bin/rer" run --script ./tool.mjs` followed by its arguments.
52
+ For example, from Downloads the Oncall PagerDuty exporter runs with:
53
+
54
+ ```sh
55
+ "$HOME/.local/bin/rer" run --script ./oncall-export.mjs pagerduty
56
+ ```
57
+
58
+ `--script` uses the Node running `rer`, including the installer's private Node;
59
+ it needs no checkout, pnpm or separate Node installation. The file path is
60
+ relative to the current folder, or to `--cwd DIR` when supplied before
61
+ `--script`. Remaining arguments go directly to the file. A package script
62
+ (`rer run NAME`) continues to use the checkout's pinned Node and pnpm.
63
+ The app start also fits on one line:
51
64
 
52
65
  ```sh
53
66
  curl -fsSL https://runeditrun.com/install.sh | sh -s -- dev just-every/run-inkwell
@@ -319,6 +332,7 @@ line that still names it. A later refresh is a version bump:
319
332
  | `@runeditrun/rer/jsonc` | JSONC reading | `scripts/base-cli/cli/jsonc.mjs` |
320
333
  | `@runeditrun/rer/parse`, `/scheduled` | CLI argument parsing, scheduled-job helpers | `scripts/base-cli/cli/parse.mjs`, `scheduled.mjs` |
321
334
  | `@runeditrun/rer/dev-identity` | dev identity helpers | `scripts/base-cli/cli/dev-identity.mjs` |
335
+ | `@runeditrun/rer/size-fixture` | `compileFixture(declaration, 'small' or 'large', { now, ownerEmail })`: a `size-check.json` shape as the ordered `[{name, sql, params}]` statements `rer size` runs on local D1 (the fleet runner's statements format), for seeding real D1 with the same rows | `scripts/base-cli/cli/size/fixture.mjs` |
322
336
  | `@runeditrun/rer/operator-installer` | `operatorInstaller`, `developmentTarget`, `previewTarget` | `scripts/base-onboarding/operator-installer.mjs` |
323
337
  | `@runeditrun/rer/local-installer` | `localInstaller` | `scripts/base-onboarding/adapter.mjs` |
324
338
  | `@runeditrun/rer/operator-install` | `installOperator` | `scripts/base-onboarding/operator-install.mjs` |
@@ -390,6 +404,29 @@ there lists its flags:
390
404
  `export`, `import`, `doctor`, `describe`, `check`, `release`,
391
405
  `release sign`, `release receipt` and `release keygen`.
392
406
 
407
+ `rer size` checks statement size against D1's limits: it fails a statement at 90
408
+ FROM items (counted with every CTE and view reference expanded) or expression
409
+ depth 90, where D1 refuses at 100 and local SQLite and Miniflare accept both.
410
+ With no flags it checks every view and trigger statement of the build's D1
411
+ migrations; `--migrations DIR` names a migrations directory instead, and
412
+ `--statements FILE` checks a statements file (`{"statements":[{"name","sql"}]}`)
413
+ against that schema. It runs in any checkout, needs no account, and exits 1 on
414
+ any failure, 0 otherwise and 3 with no build and no `--migrations`. `rer verify`
415
+ ends with the same check, inside its own job-queue slot, and fails exactly when
416
+ `rer size` would. With a `size-check.json` (or `--declaration FILE`, a
417
+ declaration kept outside the checkout) it also builds the declared shape at a
418
+ small and a large size on local D1, runs every declared flow on each through a
419
+ rows-read meter and fails a flow that passes its ceiling, reads more at large
420
+ than at small by over 10 percent plus 200 rows, answers the wrong status, has a
421
+ statement refused by local D1 or runs a statement at 90 FROM items or depth;
422
+ `--write-statements DIR` writes the statements each size ran in the fleet
423
+ runner's format. Without a `size-check.json`, verify's step checks the schema
424
+ objects and prints `Size check: undeclared (no size-check.json).` A checkout
425
+ without a seedContract runs it from the declaration's `build.wrangler` and
426
+ `build.deployDeclaration` and never forwards to a declared argv; its owner
427
+ persona needs an owner claim in `rer-setup.json` or `verification.owner` in
428
+ `agent-surface.json`.
429
+
393
430
  Anywhere: `rer list [DIR]`, `rer cli status|install|uninstall`, `rer update`,
394
431
  `rer queue NAME -- COMMAND`, `rer --version` and `rer --help`.
395
432
 
@@ -44,7 +44,7 @@ async function writeLauncher(paths) {
44
44
  const shellQuote = value => "'" + value.replaceAll("'", "'\"'\"'") + "'";
45
45
  async function closing(paths) {
46
46
  const notices = await pathAdvice(paths, process.env, { includeShellStep: false });
47
- return (notices ? notices + '\n' : '') + (process.env.RER_INSTALL_NO_NEXT ? '' : `Next, start an app: ${shellQuote(paths.launcher)} dev <owner>/<repo>\n`);
47
+ return (notices ? notices + '\n' : '') + (process.env.RER_INSTALL_NO_NEXT ? '' : `Run a downloaded JavaScript tool with the installed runtime: ${shellQuote(paths.launcher)} run --script ./tool.mjs [ARGS...]\nNext, start an app: ${shellQuote(paths.launcher)} dev <owner>/<repo>\n`);
48
48
  }
49
49
 
50
50
  export async function install({ quiet = false } = {}) {
package/global/main.mjs CHANGED
@@ -28,6 +28,9 @@ else its vendored scripts/rer.mjs.
28
28
  rer run SCRIPT [ARGS]
29
29
  Run a package.json script with the pnpm and Node the checkout pins (rer keeps
30
30
  them off PATH): where a project's docs say pnpm run X, run rer run X.
31
+ rer run --script FILE [ARGS]
32
+ Run a downloaded JavaScript file with rer's Node, including its private runtime.
33
+ Works outside a checkout; FILE is relative to here (or --cwd DIR).
31
34
  rer list [DIR] The checkouts in DIR (default: here), newest first, with whether rer dev can
32
35
  launch them, whether they are set up, and their running URL. --json for data.
33
36
  rer business ... Set up your business once and share its name, logo and brand colour
package/global/run.mjs CHANGED
@@ -6,14 +6,18 @@
6
6
  import { spawn } from 'node:child_process';
7
7
  import { readFile } from 'node:fs/promises';
8
8
  import { constants } from 'node:os';
9
- import { delimiter, dirname, join } from 'node:path';
9
+ import { delimiter, dirname, join, resolve } from 'node:path';
10
10
  import { locate } from './checkout.mjs';
11
11
  import { shared } from '../cli/shared.mjs';
12
12
 
13
13
  export const runUsage = `Usage: rer run [--cwd DIR] [SCRIPT [ARGS...]]
14
+ rer run [--cwd DIR] --script FILE [ARGS...]
14
15
  Runs a package.json script of this checkout as pnpm run SCRIPT ARGS would, with the
15
16
  pnpm and Node the checkout pins (rer keeps them off PATH). Without SCRIPT it lists
16
17
  the scripts. Where a project's docs say pnpm run X -- ARGS, run rer run X -- ARGS.
18
+ With --script, runs a JavaScript file with the Node running rer, including the
19
+ installer's private runtime. No checkout or package manager is needed. FILE is
20
+ relative to the current folder (or --cwd DIR); remaining arguments go to the file.
17
21
  `;
18
22
 
19
23
  // The checkout's pinned Node, when it differs from this one (RER_NODE_AUTO=0 keeps this one).
@@ -38,6 +42,11 @@ export async function runScript(args) {
38
42
  if (!cwd?.trim() || cwd.startsWith('-')) { process.stderr.write(`A folder is required for --cwd.\n${runUsage}`); return 2; }
39
43
  args = args.slice(2);
40
44
  }
45
+ if (args[0] === '--script') {
46
+ const file = args[1];
47
+ if (!file?.trim() || file.startsWith('-')) { process.stderr.write(`A file is required for --script.\n${runUsage}`); return 2; }
48
+ return runChild(process.execPath, [resolve(cwd ?? '.', file), ...args.slice(2)], cwd ?? process.cwd());
49
+ }
41
50
  const target = locate(cwd ? ['run', '--cwd', cwd] : ['run']);
42
51
  if (!target.root || !['first-party', 'independent'].includes(target.profile)) {
43
52
  process.stderr.write(`rer run runs inside a checkout: a folder with OPERATIONS.json at or above this one, or --cwd DIR.\n`);
@@ -62,7 +71,11 @@ export async function runScript(args) {
62
71
  }
63
72
  const { toolCommand } = await shared('tool-command.mjs');
64
73
  const [program, parameters] = toolCommand('pnpm', ['run', '--silent', ...args], process.env);
65
- const child = spawn(program, parameters, { cwd: target.root, env: process.env, stdio: 'inherit' });
74
+ return runChild(program, parameters, target.root);
75
+ }
76
+
77
+ async function runChild(program, parameters, cwd) {
78
+ const child = spawn(program, parameters, { cwd, env: process.env, stdio: 'inherit' });
66
79
  const forward = new Map(['SIGINT', 'SIGTERM', 'SIGHUP'].map(signal => [signal, () => child.kill(signal)]));
67
80
  for (const [signal, handler] of forward) process.on(signal, handler);
68
81
  try {
package/install.sh CHANGED
@@ -178,6 +178,9 @@ NODE
178
178
  if [ -n "$path_step" ]; then RER_INSTALLER_PATH_STEP=1; export RER_INSTALLER_PATH_STEP; fi
179
179
  status=0
180
180
  "$HOME/.local/bin/rer" "$@" || status=$?
181
+ if [ "$1" != business ]; then
182
+ printf 'Run a downloaded JavaScript tool with the installed runtime: "%s/.local/bin/rer" run --script ./tool.mjs [ARGS...]\n' "$HOME"
183
+ fi
181
184
  if [ -n "$path_step" ]; then
182
185
  printf '\nRequired next step: %s/.local/bin is not on your PATH, so a bare `rer` in a new terminal says "rer: command not found". Run this in the terminal you will use, and add the same line to your shell startup file (~/.zshrc for zsh, ~/.bashrc for bash):\n export PATH="$HOME/.local/bin:$PATH"\nOther shells, such as fish: run %s/.local/bin/rer cli path to see the line for yours. Until then, start rer with %s/.local/bin/rer. This installer changes no shell file.\n' "$HOME" "$HOME" "$HOME"
183
186
  fi