ezship 0.1.16 → 0.1.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.
package/commands.mjs CHANGED
@@ -5,7 +5,7 @@
5
5
  //
6
6
  // A Builder works on a *working copy* -- a directory for the CLI, IndexedDB for the browser. `pull` mirrors the
7
7
  // Site's shared files into it, `push` publishes it, `deploy` ships the shared files. ls/cat/put/edit/delete/mv act
8
- // on the working copy only. See CONTEXT.md and docs/adr/0004.
8
+ // on the working copy only. See CONTEXT.md and docs/adr/0204.
9
9
 
10
10
  import { extractTarget, usesWorkingCopy } from "./connections.mjs";
11
11
  import { parseCron } from "./cron.mjs";
@@ -22,10 +22,28 @@ import {
22
22
  } from "./schema.mjs";
23
23
  import { parseSessionDeclaration, SESSION_FILE } from "./session.mjs";
24
24
  import { ACCESS_FILE, checkAccess, parseGate } from "./access.mjs";
25
- import { readWorkflow, workflowShapes } from "./workflow.mjs";
25
+ import { checkWorkflowNames, readWorkflow, workflowShapes } from "./workflow.mjs";
26
+
27
+ import { ASSET_TYPES, ATTACHMENT_TYPES } from "./paths.mjs";
26
28
 
27
29
  export { MAX_MESSAGE_CHARS, messageText } from "./schema.mjs";
28
30
 
31
+ // The page's side of the wire lives in paths.mjs, the one module the Framework bundles (docs/adr/0216).
32
+ export {
33
+ ACCESS_RULES_PATH,
34
+ ASSET_PATH,
35
+ ASSET_TYPES,
36
+ ATTACHMENT_PATH,
37
+ ATTACHMENT_TYPES,
38
+ attachmentContentType,
39
+ DOCUMENT_BASE_PATH,
40
+ FUNCTION_BASE_PATH,
41
+ LIVE_STREAM_PATH,
42
+ LIVE_VERSIONS_PATH,
43
+ SCOPE_PATH,
44
+ VERSIONS_HEADER,
45
+ } from "./paths.mjs";
46
+
29
47
  export {
30
48
  parseSessionDeclaration,
31
49
  sessionValueError,
@@ -54,7 +72,7 @@ export {
54
72
 
55
73
  /** @typedef {import("./commands.d.mts").Workspace} Workspace */
56
74
 
57
- // ---- what a Site is (docs/adr/0012) -------------------------------------------------------------------
75
+ // ---- what a Site is (docs/adr/0209) -------------------------------------------------------------------
58
76
  // Also re-exported by the platform's src/shared.ts.
59
77
 
60
78
  /**
@@ -68,7 +86,7 @@ export const MAIN_FILE = "App.tsx";
68
86
  */
69
87
  export const CONTEXT_FILE = "CONTEXT.md";
70
88
  /**
71
- * docs/<name>.md in a Site or the Global Workspace (ADR 0144): plain Markdown for Builders, pushed and
89
+ * docs/<name>.md in a Site or the Global Workspace (ADR 0209): plain Markdown for Builders, pushed and
72
90
  * versioned like code, never built or served. CONTEXT.md's inventory lists each one.
73
91
  * @type {typeof import("./commands.d.mts").DOCS_DIR}
74
92
  */
@@ -78,7 +96,7 @@ export function docName(path) {
78
96
  const match = /^docs\/([a-z0-9][a-z0-9-]{0,63})\.md$/.exec(path);
79
97
  return match ? match[1] : null;
80
98
  }
81
- /** Why a docs/ path is malformed (ADR 0144); `shape` ends the message. */
99
+ /** Why a docs/ path is malformed (ADR 0209); `shape` ends the message. */
82
100
  const docPathError = (/** @type {string} */ path, /** @type {string} */ shape) =>
83
101
  path.slice(DOCS_DIR.length).includes("/")
84
102
  ? `${path}: docs/ has no subfolders. ${shape}`
@@ -91,7 +109,7 @@ export const PAGES_DIR = "pages/";
91
109
  /** @type {typeof import("./commands.d.mts").COMPONENTS_DIR} */
92
110
  export const COMPONENTS_DIR = "components/";
93
111
  /**
94
- * hooks/use<Name>.ts (ADR 0091): one custom hook per file, default-exported under the file's name, in a Site or
112
+ * hooks/use<Name>.ts (ADR 0209): one custom hook per file, default-exported under the file's name, in a Site or
95
113
  * the Global Workspace (imported as `global/hooks/use<Name>`). Browser code with a component's imports and Rules.
96
114
  * @type {typeof import("./commands.d.mts").HOOKS_DIR}
97
115
  */
@@ -106,65 +124,33 @@ export const FUNCTIONS_DIR = "functions/";
106
124
  /** @type {typeof import("./commands.d.mts").FUNCTION_ARTIFACT} */
107
125
  export const FUNCTION_ARTIFACT = "_server/functions.json";
108
126
  /**
109
- * The Instance's Table rules (docs/adr/0099), compiled at Global Push: private like FUNCTION_ARTIFACT, and
127
+ * The Instance's Table rules (docs/adr/0226), compiled at Global Push: private like FUNCTION_ARTIFACT, and
110
128
  * never part of a Site's build.
111
129
  * @type {typeof import("./commands.d.mts").RULES_ARTIFACT}
112
130
  */
113
131
  export const RULES_ARTIFACT = "_server/rules.json";
114
132
  /**
115
- * The Instance's scheduled jobs (ADR 0136), compiled at Global Push beside the rules: private, and never part
133
+ * The Instance's scheduled jobs (ADR 0230), compiled at Global Push beside the rules: private, and never part
116
134
  * of a Site's build.
117
135
  * @type {typeof import("./commands.d.mts").JOBS_ARTIFACT}
118
136
  */
119
137
  export const JOBS_ARTIFACT = "_server/jobs.json";
120
- /** @type {typeof import("./commands.d.mts").FUNCTION_BASE_PATH} */
121
- export const FUNCTION_BASE_PATH = "/_ez/functions";
122
138
  /** @type {typeof import("./commands.d.mts").DOCUMENTS_DIR} */
123
139
  export const DOCUMENTS_DIR = "documents/";
124
140
  /** @type {typeof import("./commands.d.mts").DOCUMENT_ARTIFACT} */
125
141
  export const DOCUMENT_ARTIFACT = "_server/documents.json";
126
- /** @type {typeof import("./commands.d.mts").DOCUMENT_BASE_PATH} */
127
- export const DOCUMENT_BASE_PATH = "/_ez/documents";
128
142
  /** @type {typeof import("./commands.d.mts").DOCUMENT_RE} */
129
143
  export const DOCUMENT_RE = /^documents\/([A-Z][A-Za-z0-9]*)\.tsx$/;
130
144
  /** @type {typeof import("./commands.d.mts").MAX_RENDER_INPUT_BYTES} */
131
145
  export const MAX_RENDER_INPUT_BYTES = 1_000_000;
132
146
  /**
133
- * The Document a Global `documents/<Name>.tsx` file holds, or null for any other path (docs/adr/0105).
147
+ * The Document a Global `documents/<Name>.tsx` file holds, or null for any other path (docs/adr/0233).
134
148
  * @type {typeof import("./commands.d.mts").documentName}
135
149
  */
136
150
  export function documentName(path) {
137
151
  const m = DOCUMENT_RE.exec(path);
138
152
  return m ? m[1] : null;
139
153
  }
140
- /**
141
- * A page's live Table versions (docs/adr/0053): `GET <prefix>/_ez/db/stream` answers `text/event-stream`, each
142
- * `versions` event the complete map the viewer may read; `GET <prefix>/_ez/db/versions` is the same map once.
143
- * @type {typeof import("./commands.d.mts").LIVE_STREAM_PATH}
144
- */
145
- export const LIVE_STREAM_PATH = "/_ez/db/stream";
146
- /** @type {typeof import("./commands.d.mts").LIVE_VERSIONS_PATH} */
147
- export const LIVE_VERSIONS_PATH = "/_ez/db/versions";
148
- /**
149
- * The rules of the Tables this artifact declares (docs/adr/0098): `GET <prefix>/_ez/access` answers
150
- * `{ rules: { [table]: { read, write } }, workflows: { [table]: WorkflowMeta } }`, what `useCan` evaluates
151
- * and `useWorkflow` shows (docs/adr/0103). The Host's answer to a write is the authority; these only let a
152
- * page hide what it would refuse.
153
- * @type {typeof import("./commands.d.mts").ACCESS_RULES_PATH}
154
- */
155
- export const ACCESS_RULES_PATH = "/_ez/access";
156
- /**
157
- * The active scope for the Framework's switcher (docs/adr/0098): `GET <prefix>/_ez/scope` answers
158
- * `{ scope: { column, key, values: [{ value, label }], active } | null }`.
159
- * @type {typeof import("./commands.d.mts").SCOPE_PATH}
160
- */
161
- export const SCOPE_PATH = "/_ez/scope";
162
- /**
163
- * The response header on a page's writes and function calls: the viewer's version map read after the commit,
164
- * as JSON, so the page can wait until its live queries show the write.
165
- * @type {typeof import("./commands.d.mts").VERSIONS_HEADER}
166
- */
167
- export const VERSIONS_HEADER = "ez-versions";
168
154
  /** @type {typeof import("./commands.d.mts").FUNCTION_NAME_RE} */
169
155
  export const FUNCTION_NAME_RE = /^[a-z][A-Za-z0-9]{0,63}$/;
170
156
  /** @type {typeof import("./commands.d.mts").functionName} */
@@ -173,7 +159,7 @@ export function functionName(path) {
173
159
  return match ? match[1] : null;
174
160
  }
175
161
  /**
176
- * local/<name>.ts: a Site's local functions, Node code the Desktop runs on the Member's computer (ADR 0048).
162
+ * local/<name>.ts: a Site's local functions, Node code the Desktop runs on the Member's computer (ADR 0235).
177
163
  * @type {typeof import("./commands.d.mts").LOCAL_DIR}
178
164
  */
179
165
  export const LOCAL_DIR = "local/";
@@ -187,7 +173,7 @@ export function localFunctionName(path) {
187
173
  return match ? match[1] : null;
188
174
  }
189
175
  /**
190
- * jobs/<name>.ts in the Global Workspace: the Instance's scheduled jobs (ADRs 0076, 0136), server code no browser
176
+ * jobs/<name>.ts in the Global Workspace: the Instance's scheduled jobs (ADR 0230), server code no browser
191
177
  * can call; schedules.json runs them.
192
178
  * @type {typeof import("./commands.d.mts").JOBS_DIR}
193
179
  */
@@ -198,7 +184,7 @@ export function jobName(path) {
198
184
  return match ? match[1] : null;
199
185
  }
200
186
  /**
201
- * listeners/<name>.ts: a Site's Listeners (ADR 0092), server code run once for each event that reaches it;
187
+ * listeners/<name>.ts: a Site's Listeners (ADR 0231), server code run once for each event that reaches it;
202
188
  * listeners.json names them and how their events arrive.
203
189
  * @type {typeof import("./commands.d.mts").LISTENERS_DIR}
204
190
  */
@@ -215,7 +201,7 @@ export const LISTENER_MAX = 20;
215
201
  /** Where a deployed Listener receives on the app origin: `<prefix>/_ez/listeners/<name>`. */
216
202
  /** @type {typeof import("./commands.d.mts").LISTENER_BASE_PATH} */
217
203
  export const LISTENER_BASE_PATH = "/_ez/listeners/";
218
- /** How a sending service proves a delivery (ADR 0092); data, grown by platform release. */
204
+ /** How a sending service proves a delivery (ADR 0231); data, grown by platform release. */
219
205
  /** @type {typeof import("./commands.d.mts").WEBHOOK_SCHEMES} */
220
206
  export const WEBHOOK_SCHEMES = Object.freeze(
221
207
  /** @type {const} */ (["standard", "stripe", "github", "token"]),
@@ -227,7 +213,7 @@ export const LISTENER_OVERLAP_HOURS = Object.freeze({ default: 24, max: 168 });
227
213
  /** @type {typeof import("./commands.d.mts").LISTENER_BODY_MAX} */
228
214
  export const LISTENER_BODY_MAX = 256_000;
229
215
  /**
230
- * The Data API (docs/adr/0119, docs/adr/0151): other systems reach an Instance's data under `/_ez/api/` on its
216
+ * The Data API (docs/adr/0232): other systems reach an Instance's data under `/_ez/api/` on its
231
217
  * app origin with an API Key, `Authorization: Bearer ezk_...`.
232
218
  * @type {typeof import("./commands.d.mts").API_BASE_PATH}
233
219
  */
@@ -343,7 +329,7 @@ export function parseListeners(source, files) {
343
329
  }
344
330
 
345
331
  /**
346
- * The optional Global file that schedules jobs on a UTC cron (ADRs 0076, 0136); a Global Push activates it.
332
+ * The optional Global file that schedules jobs on a UTC cron (ADR 0230); a Global Push activates it.
347
333
  * @type {typeof import("./commands.d.mts").SCHEDULES_FILE}
348
334
  */
349
335
  export const SCHEDULES_FILE = "schedules.json";
@@ -428,7 +414,7 @@ export function parseSchedules(source, files) {
428
414
  }
429
415
 
430
416
  /**
431
- * The optional page.json of a Site and of the Global Workspace (ADR 0148): the deployed page's settings. The
417
+ * The optional page.json of a Site and of the Global Workspace (ADR 0209): the deployed page's settings. The
432
418
  * Global one sets every Site's, a Site's own overrides it key by key, and the Pipeline writes the result
433
419
  * into the page's head.
434
420
  * @type {typeof import("./commands.d.mts").PAGE_FILE}
@@ -503,8 +489,9 @@ export function pageIcon(files, global) {
503
489
  }
504
490
 
505
491
  /**
506
- * lib/<name>.ts in the Global Workspace (ADR 0077): pure TypeScript every Site's pages, components and server
492
+ * lib/<name>.ts in the Global Workspace (ADR 0210): pure TypeScript every Site's pages, components and server
507
493
  * functions import as `global/lib/<name>`. Named exports; whatever reads or writes takes the database as an argument.
494
+ * A Site has the same folder for helpers only it uses (ADR 0209), imported by path (`./lib/<name>`).
508
495
  * @type {typeof import("./commands.d.mts").LIB_DIR}
509
496
  */
510
497
  export const LIB_DIR = "lib/";
@@ -514,7 +501,7 @@ export function libModuleName(path) {
514
501
  return match ? match[1] : null;
515
502
  }
516
503
  /**
517
- * Table rules (docs/adr/0099): `rules/<table>.ts` in the Global Workspace, named after a published Table.
504
+ * Table rules (docs/adr/0226): `rules/<table>.ts` in the Global Workspace, named after a published Table.
518
505
  * @type {typeof import("./commands.d.mts").RULES_DIR}
519
506
  */
520
507
  export const RULES_DIR = "rules/";
@@ -524,7 +511,7 @@ export function ruleTableName(path) {
524
511
  return match ? match[1] : null;
525
512
  }
526
513
  /**
527
- * Workflows (docs/adr/0103): `workflows/<table>.ts` in the Global Workspace, named after a published Table.
514
+ * Workflows (docs/adr/0227): `workflows/<table>.ts` in the Global Workspace, named after a published Table.
528
515
  * @type {typeof import("./commands.d.mts").WORKFLOWS_DIR}
529
516
  */
530
517
  export const WORKFLOWS_DIR = "workflows/";
@@ -534,13 +521,13 @@ export function workflowTableName(path) {
534
521
  return match ? match[1] : null;
535
522
  }
536
523
  /**
537
- * Live server code of the Global Workspace (docs/adr/0099, 0103): a rules or a workflow file, compiled at
524
+ * Live server code of the Global Workspace (docs/adr/0226, 0227): a rules or a workflow file, compiled at
538
525
  * Push into the Instance's rules artifact. Both import what server code may.
539
526
  * @param {string} path
540
527
  */
541
528
  const liveCodeTable = (path) => ruleTableName(path) ?? workflowTableName(path);
542
529
  /**
543
- * Desktop release files (ADR 0048): where every Instance app origin serves the installer and its update feed,
530
+ * Desktop release files (ADR 0235): where every Instance app origin serves the installer and its update feed,
544
531
  * what a release file may be called, and how large one may be.
545
532
  * @type {typeof import("./commands.d.mts").DESKTOP_PATH}
546
533
  */
@@ -550,7 +537,7 @@ export const DESKTOP_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
550
537
  /** @type {typeof import("./commands.d.mts").MAX_DESKTOP_FILE_BYTES} */
551
538
  export const MAX_DESKTOP_FILE_BYTES = 100_000_000;
552
539
  /**
553
- * The packages Site UI and Global components and hooks may import by name (docs/adr/0114): declarative React,
540
+ * The packages Site UI and Global components and hooks may import by name (docs/adr/0209): declarative React,
554
541
  * pinned by the Pipeline, added only by a platform release.
555
542
  * @type {typeof import("./commands.d.mts").SITE_PACKAGES}
556
543
  */
@@ -611,11 +598,17 @@ export const TYPES_FILE = "db/types.d.ts";
611
598
  export const BUILD_ENTRY = "index.html";
612
599
  /** @type {typeof import("./commands.d.mts").BUILD_CONFIG_MARKER} */
613
600
  export const BUILD_CONFIG_MARKER = "<!--ez:config-->";
601
+ /**
602
+ * The attribute on the page's `modulepreload` link for the vendor chunk (docs/adr/0216): how the app host
603
+ * finds the chunk of React and the Framework, which it may serve once for all of an Instance's Sites.
604
+ * @type {typeof import("./commands.d.mts").BUILD_VENDOR_ATTR}
605
+ */
606
+ export const BUILD_VENDOR_ATTR = "data-ez-vendor";
614
607
 
615
608
  /**
616
609
  * The compiler options every type check of Site code uses: the Pipeline's and the editor's tsconfig.json both
617
- * spread these, so local \`tsc\` and \`ez check\` agree (docs/adr/0078). \`noUncheckedIndexedAccess\` is
618
- * left off (docs/adr/0086).
610
+ * spread these, so local \`tsc\` and \`ez check\` agree (docs/adr/0236). \`noUncheckedIndexedAccess\` is
611
+ * left off (docs/adr/0236).
619
612
  * @type {typeof import("./commands.d.mts").COMPILER_OPTIONS}
620
613
  */
621
614
  export const COMPILER_OPTIONS = Object.freeze({
@@ -654,48 +647,17 @@ export const GLOBAL_ID = "global";
654
647
  */
655
648
  export const SHELL_FILE = "Shell.tsx";
656
649
 
657
- // ---- Instance assets (docs/adr/0014): a name, an immutable object, a frozen URL; Site code says asset("logo").
650
+ // ---- Instance assets (docs/adr/0213): a name, an immutable object, a frozen URL; Site code says asset("logo").
658
651
 
659
652
  /**
660
653
  * An asset's name: the API Site code uses (`asset("logo")`), unique within the Instance, never renamed.
661
654
  * @type {typeof import("./commands.d.mts").ASSET_NAME_RE}
662
655
  */
663
656
  export const ASSET_NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
664
- /**
665
- * Allowed asset types by extension. Limits are data: loosened by platform release, never per Instance.
666
- * @type {typeof import("./commands.d.mts").ASSET_TYPES}
667
- */
668
- export const ASSET_TYPES = Object.freeze({
669
- png: "image/png",
670
- jpg: "image/jpeg",
671
- jpeg: "image/jpeg",
672
- gif: "image/gif",
673
- webp: "image/webp",
674
- avif: "image/avif",
675
- svg: "image/svg+xml",
676
- mp4: "video/mp4",
677
- webm: "video/webm",
678
- mp3: "audio/mpeg",
679
- m4a: "audio/mp4",
680
- wav: "audio/wav",
681
- pdf: "application/pdf",
682
- txt: "text/plain",
683
- csv: "text/csv",
684
- json: "application/json",
685
- docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
686
- xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
687
- pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
688
- zip: "application/zip",
689
- });
690
657
  /** @type {typeof import("./commands.d.mts").MAX_ASSET_BYTES} */
691
658
  export const MAX_ASSET_BYTES = 100_000_000;
692
659
  /** @type {typeof import("./commands.d.mts").MAX_INSTANCE_ASSET_BYTES} */
693
660
  export const MAX_INSTANCE_ASSET_BYTES = 2_000_000_000;
694
- /**
695
- * Where a Site's app serves the Instance's assets: `<prefix>/_ez/files/<name>`.
696
- * @type {typeof import("./commands.d.mts").ASSET_PATH}
697
- */
698
- export const ASSET_PATH = "/_ez/files";
699
661
 
700
662
  /**
701
663
  * The content type an asset file gets from its extension, or null when the type is not allowed.
@@ -706,12 +668,7 @@ export function assetContentType(filename) {
706
668
  return m ? (ASSET_TYPES[m[1].toLowerCase()] ?? null) : null;
707
669
  }
708
670
 
709
- // ---- App Attachments (docs/adr/0047): a file on one FILE column of one row; pages upload with db.upload.
710
- /**
711
- * Allowed attachment types by extension: the asset table. Limits are data, loosened by release.
712
- * @type {typeof import("./commands.d.mts").ATTACHMENT_TYPES}
713
- */
714
- export const ATTACHMENT_TYPES = Object.freeze({ ...ASSET_TYPES });
671
+ // ---- App Attachments (docs/adr/0221): a file on one FILE column of one row; pages upload with db.upload.
715
672
  /** @type {typeof import("./commands.d.mts").MAX_ATTACHMENT_BYTES} */
716
673
  export const MAX_ATTACHMENT_BYTES = 25_000_000;
717
674
  /** The Instance's attachment pool, separate from its assets. @type {typeof import("./commands.d.mts").MAX_INSTANCE_ATTACHMENT_BYTES} */
@@ -722,20 +679,6 @@ export const MAX_UNBOUND_ATTACHMENTS = 20;
722
679
  export const MAX_UNBOUND_ATTACHMENT_BYTES = 250_000_000;
723
680
  /** An upload no row has bound within this time is swept. @type {typeof import("./commands.d.mts").UNBOUND_ATTACHMENT_TTL_MS} */
724
681
  export const UNBOUND_ATTACHMENT_TTL_MS = 86_400_000;
725
- /**
726
- * Where a Site's app takes and serves attachments: `POST <prefix>/_ez/attachments/<table>/<column>?name=<file>`
727
- * and `GET <prefix>/_ez/attachments/<id>`.
728
- * @type {typeof import("./commands.d.mts").ATTACHMENT_PATH}
729
- */
730
- export const ATTACHMENT_PATH = "/_ez/attachments";
731
- /**
732
- * The content type an attachment gets from its filename's extension, or null when the type is not allowed.
733
- * @type {typeof import("./commands.d.mts").attachmentContentType}
734
- */
735
- export function attachmentContentType(filename) {
736
- const m = /\.([A-Za-z0-9]+)$/.exec(filename);
737
- return m ? (ATTACHMENT_TYPES[m[1].toLowerCase()] ?? null) : null;
738
- }
739
682
  /**
740
683
  * pages/index.tsx, or lowercase segments joined by dots, `$name` for a parameter: pages/orders.$id.tsx.
741
684
  * @type {typeof import("./commands.d.mts").PAGE_RE}
@@ -759,7 +702,7 @@ export function isValidFilePath(path) {
759
702
  const INVALID_PATH = (p) =>
760
703
  `Invalid path: ${p}. Use relative paths like components/Hello.tsx (no leading slash, no ..).`;
761
704
 
762
- const SITE_SHAPE = `A Site is ${MAIN_FILE}, required ${CONTEXT_FILE}, ${PAGES_DIR}<route>.tsx, ${COMPONENTS_DIR}<Name>.tsx, ${HOOKS_DIR}use<Name>.ts, ${FUNCTIONS_DIR}<name>.ts, ${LOCAL_DIR}<name>.ts, ${LISTENERS_DIR}<name>.ts, ${CONSTANTS_FILE}, ${DOCS_DIR}<name>.md (Markdown docs), optional ${LISTENERS_FILE}, optional ${PAGE_FILE} (the browser icon) and optional ${STYLE_FILE}. Schema, generated types and scheduled jobs belong to the Global Workspace.`;
705
+ const SITE_SHAPE = `A Site is ${MAIN_FILE}, required ${CONTEXT_FILE}, ${PAGES_DIR}<route>.tsx, ${COMPONENTS_DIR}<Name>.tsx, ${HOOKS_DIR}use<Name>.ts, ${LIB_DIR}<name>.ts (helpers), ${FUNCTIONS_DIR}<name>.ts, ${LOCAL_DIR}<name>.ts, ${LISTENERS_DIR}<name>.ts, ${CONSTANTS_FILE}, ${DOCS_DIR}<name>.md (Markdown docs), optional ${LISTENERS_FILE}, optional ${PAGE_FILE} (the browser icon) and optional ${STYLE_FILE}. Schema, generated types and scheduled jobs belong to the Global Workspace.`;
763
706
 
764
707
  /**
765
708
  * Why required context is invalid, or null. Content quality is guided by the instructions, not parsed.
@@ -771,7 +714,7 @@ export function contextError(content) {
771
714
  : `${CONTEXT_FILE} is required and must contain text. Create or populate it with this Site's or Instance's purpose, workflows and constraints using ez put ${CONTEXT_FILE} (ez global put ${CONTEXT_FILE} for Global).`;
772
715
  }
773
716
 
774
- // ---- the generated file inventory in CONTEXT.md (docs/adr/0108) ------------------------------------------
717
+ // ---- the generated file inventory in CONTEXT.md (docs/adr/0215) ------------------------------------------
775
718
 
776
719
  /** @type {typeof import("./commands.d.mts").INVENTORY_START} */
777
720
  export const INVENTORY_START =
@@ -797,7 +740,7 @@ function docSummary(source) {
797
740
  return sentence.length > SUMMARY_MAX ? `${sentence.slice(0, SUMMARY_MAX - 1)}…` : sentence;
798
741
  }
799
742
 
800
- /** A doc's first Markdown heading (ADR 0144), or null when it has none. @param {string} source */
743
+ /** A doc's first Markdown heading (ADR 0209), or null when it has none. @param {string} source */
801
744
  function headingSummary(source) {
802
745
  const heading = /^#{1,6}[ \t]+(.+?)[ \t#]*$/m.exec(source)?.[1]?.trim();
803
746
  if (!heading) return null;
@@ -806,7 +749,7 @@ function headingSummary(source) {
806
749
 
807
750
  /**
808
751
  * The inventory block for a Working Copy: one line per .ts/.tsx file but generated ones, with the first
809
- * sentence of its first doc comment, and one per docs/<name>.md with its first heading (ADR 0144), sorted by
752
+ * sentence of its first doc comment, and one per docs/<name>.md with its first heading (ADR 0209), sorted by
810
753
  * path, between INVENTORY_START and INVENTORY_END.
811
754
  * @type {typeof import("./commands.d.mts").contextInventory}
812
755
  */
@@ -862,7 +805,7 @@ export function pageRoute(path) {
862
805
  );
863
806
  }
864
807
 
865
- /** Why a hooks/ path is malformed (ADR 0091); `shape` ends the message. */
808
+ /** Why a hooks/ path is malformed (ADR 0209); `shape` ends the message. */
866
809
  const hookPathError = (/** @type {string} */ path, /** @type {string} */ shape) => {
867
810
  const rest = path.slice(HOOKS_DIR.length);
868
811
  if (rest.includes("/")) return `${path}: hooks/ has no subfolders. ${shape}`;
@@ -879,9 +822,6 @@ export function siteFileError(path) {
879
822
  if (!isValidFilePath(path)) return INVALID_PATH(path);
880
823
  if (functionName(path) || localFunctionName(path) || listenerName(path)) return null;
881
824
  if (path === LISTENERS_FILE || path === PAGE_FILE) return null;
882
- // ADR 0136: schedules belong to the Instance.
883
- if (path === SCHEDULES_FILE || path.startsWith(JOBS_DIR))
884
- return `${path}: scheduled jobs belong to the Global Workspace now: global/${SCHEDULES_FILE} and global/${JOBS_DIR}<name>.ts (ez global put). Move what a job shares with this Site to global/lib/<name>.ts and global/constants.ts, then delete the Site's copy.`;
885
825
  if (path.startsWith(LISTENERS_DIR)) {
886
826
  if (path.slice(LISTENERS_DIR.length).includes("/"))
887
827
  return `${path}: listeners/ has no subfolders. ${SITE_SHAPE}`;
@@ -894,8 +834,6 @@ export function siteFileError(path) {
894
834
  }
895
835
  if (path === MAIN_FILE || path === CONTEXT_FILE || path === CONSTANTS_FILE || path === STYLE_FILE)
896
836
  return null;
897
- if (path === SCHEMA_FILE || path === TYPES_FILE)
898
- return `${path} now belongs to the Global Workspace. Move the schema to global/db/schema.sql, remove NOT NULL, push global, and delete the Site copies. Import types from "global/db/types".`;
899
837
  if (path.startsWith(PAGES_DIR)) {
900
838
  if (pageRoute(path) !== null) return null;
901
839
  if (path.slice(PAGES_DIR.length).includes("/"))
@@ -911,6 +849,12 @@ export function siteFileError(path) {
911
849
  return `${path}: <Name> is PascalCase (components/OrderRow.tsx). ${SITE_SHAPE}`;
912
850
  }
913
851
  if (path.startsWith(HOOKS_DIR)) return hookName(path) ? null : hookPathError(path, SITE_SHAPE);
852
+ if (path.startsWith(LIB_DIR)) {
853
+ if (libModuleName(path)) return null;
854
+ if (path.slice(LIB_DIR.length).includes("/"))
855
+ return `${path}: lib/ has no subfolders. ${SITE_SHAPE}`;
856
+ return `${path}: a lib module is lib/<name>.ts, a lowercase-first name (lib/pricing.ts). ${SITE_SHAPE}`;
857
+ }
914
858
  if (path.startsWith(DOCS_DIR)) return docName(path) ? null : docPathError(path, SITE_SHAPE);
915
859
  return `${path} is not a Site file. ${SITE_SHAPE}`;
916
860
  }
@@ -1012,7 +956,6 @@ export default function App() {
1012
956
  <>
1013
957
  <Nav>
1014
958
  <Link to="/">Home</Link>
1015
- <Link to="/about">About</Link>
1016
959
  </Nav>
1017
960
  <Outlet />
1018
961
  </>
@@ -1033,13 +976,6 @@ export default function Home() {
1033
976
  </>
1034
977
  );
1035
978
  }
1036
- `,
1037
- "pages/about.tsx": `import { APP } from "../constants";
1038
-
1039
- /** What this app is. */
1040
- export default function About() {
1041
- return <p>About {APP.name}.</p>;
1042
- }
1043
979
  `,
1044
980
  "components/Hello.tsx": `/** A greeting with the app's name. */
1045
981
  export default function Hello({ name }: { name: string }) {
@@ -1049,7 +985,9 @@ export default function Hello({ name }: { name: string }) {
1049
985
  [CONSTANTS_FILE]: `/** The app's name and other plain values its pages share. */
1050
986
  export const APP = { name: "My app" } as const;
1051
987
  `,
1052
- [STYLE_FILE]: `body { font-family: system-ui, sans-serif; margin: 2rem; }
988
+ [STYLE_FILE]: `/* This Site's own classes, loaded after the Theme (global/style.css). The Theme owns the look: take every
989
+ colour, radius and shadow from its tokens (background: var(--surface); border: 1px solid var(--line)), and
990
+ change the look itself there, for every Site at once. */
1053
991
  `,
1054
992
  });
1055
993
 
@@ -1080,9 +1018,10 @@ Generated db/types.d.ts is the reference for row types; do not copy it here.
1080
1018
  ## Shared UI
1081
1019
  Map components, constants, Shell.tsx and the theme to their responsibilities and usage.
1082
1020
  The Instance started with a theme (style.css: tokens in :root, then the classes), a Shell (the top bar;
1083
- BRAND in constants.ts) and the components Button, PageHeader, Panel, Stat, Badge, StateBadge, Notice,
1084
- Dialog, ConfirmDialog, Tabs, FilterChips, SearchBox, DataTable, Pager, DetailList, Field, Empty, Money,
1085
- When and Yes; edit, replace or delete them, and record here what you decide about them.
1021
+ BRAND in constants.ts) and the components Button, PageHeader, Panel, Stat, Stats, Badge, StateBadge, Notice,
1022
+ Dialog, ConfirmDialog, Tabs, Toolbar, FilterChips, SearchBox, DataTable, Pager, DetailList, Board, BoardColumn,
1023
+ Card, Form, Field, TextInput, NumberInput, SelectInput, DateInput, TextArea, Checkbox, Empty, Money, When and
1024
+ Yes; edit, replace or delete them, and record here what you decide about them.
1086
1025
 
1087
1026
  ## Decisions and constraints
1088
1027
  Record shared decisions, their reasons, known limitations and open questions.
@@ -1094,7 +1033,7 @@ Record shared decisions, their reasons, known limitations and open questions.
1094
1033
 
1095
1034
  /**
1096
1035
  * What a new Instance's Global Workspace starts with, on top of DEFAULT_GLOBAL_FILES: a theme, a Shell with a
1097
- * nav slot and the menu, and the components every suite so far has rebuilt (docs/adr/0108, 0147). Written once at
1036
+ * nav slot and the menu, and the components every suite so far has rebuilt (docs/adr/0215). Written once at
1098
1037
  * Instance creation as Version 0; a customer edits, replaces or deletes them like any global file. Not a
1099
1038
  * Framework Kit (`planning/react-sites/issues/01`): nothing here is imported unless a Site imports it.
1100
1039
  * @type {typeof import("./commands.d.mts").STARTER_GLOBAL_FILES}
@@ -1134,8 +1073,6 @@ export const STARTER_GLOBAL_FILES = Object.freeze({
1134
1073
  --control: 2.25rem;
1135
1074
  --font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
1136
1075
  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
1137
- /* Kept for Site styles written against the first starter theme. */
1138
- --accent: var(--primary-soft);
1139
1076
  }
1140
1077
  /* Fingers need bigger targets than a mouse: every control grows on a touch screen. */
1141
1078
  @media (pointer: coarse) {
@@ -1343,6 +1280,38 @@ table.data th.num .sort { flex-direction: row-reverse; }
1343
1280
  .stat.info .value { color: var(--info); }
1344
1281
  .stat.warn .value { color: var(--warn); }
1345
1282
  .stat.danger .value { color: var(--danger); }
1283
+ /* Stats: Stat tiles in one row, all one width, wrapping as the page narrows. */
1284
+ .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(170px, 1fr)); gap: 12px; }
1285
+
1286
+ /* ---- Toolbar: the controls above a list, its aside at the far end ---- */
1287
+ .toolbar > .toolbar-aside { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-left: auto; }
1288
+ .panel > .toolbar,
1289
+ .panel > .panel-body > .toolbar:first-child { padding: 12px 16px; border-bottom: 1px solid var(--line); }
1290
+ .panel > .panel-body:not(.flush) > .toolbar:first-child { margin: -16px -16px 16px; }
1291
+
1292
+ /* ---- Board, BoardColumn, Card: columns of cards side by side ---- */
1293
+ .board { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 16px; align-items: start; }
1294
+ .board-column { display: flex; flex-direction: column; background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius-lg); box-shadow: var(--shadow); min-width: 0; }
1295
+ .board-column > .board-head { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 12px 14px; border-bottom: 1px solid var(--line); }
1296
+ .board-column > .board-head .board-title { display: flex; align-items: center; gap: 8px; margin-right: auto; min-width: 0; }
1297
+ .board-column > .board-head h3 { font-size: 0.9375rem; }
1298
+ .board-column > .board-head .board-count { padding: 0 8px; border-radius: 999px; background: var(--surface-2); color: var(--muted); font-size: 0.8125rem; font-variant-numeric: tabular-nums; }
1299
+ .board-column > .board-hint { padding: 8px 14px 0; color: var(--muted); font-size: 0.8125rem; }
1300
+ .board-column > .board-cards { display: flex; flex-direction: column; gap: 8px; padding: 12px 14px; }
1301
+ .board-column .board-empty { color: var(--muted); font-size: 0.8125rem; text-align: center; padding: 12px 0; }
1302
+ .card { display: flex; flex-direction: column; gap: 4px; padding: 10px 12px; background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius); color: var(--text); text-decoration: none; min-width: 0; }
1303
+ a.card:hover { background: var(--hover); border-color: var(--line-strong); }
1304
+ .card > .card-head { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 6px 8px; }
1305
+ .card > .card-head .card-title { font-weight: 600; overflow-wrap: anywhere; }
1306
+ .card > .card-meta { color: var(--muted); font-size: 0.8125rem; }
1307
+
1308
+ /* ---- Form: fields in one column or two, its buttons at the end ---- */
1309
+ .form { display: flex; flex-direction: column; gap: 16px; }
1310
+ .form > .form-fields { display: grid; grid-template-columns: minmax(0, 1fr); gap: 14px 16px; align-items: start; }
1311
+ @media (min-width: 640px) { .form > .form-fields.two { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
1312
+ .form > .form-fields.two > .field:has(textarea) { grid-column: 1 / -1; }
1313
+ .form > .form-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 8px; }
1314
+ .field.check { flex-direction: row; align-items: center; gap: 8px; }
1346
1315
 
1347
1316
  /* ---- Notice ---- */
1348
1317
  .notice { display: flex; align-items: flex-start; gap: 10px; padding: 10px 12px; border-radius: var(--radius); border: 1px solid transparent; background: var(--info-bg); color: var(--text); border-left: 3px solid var(--info); }
@@ -1434,19 +1403,21 @@ export default function Badge({
1434
1403
  import { Link, run, useFormStatus } from "@ezship/react";
1435
1404
 
1436
1405
  /**
1437
- * A button. \`action\` may be async: the button shows a spinner and ignores clicks until it settles, and a
1406
+ * A button. \`action\` (or \`onClick\`, the same thing) may be async: the button shows a spinner and ignores clicks until it settles, and a
1438
1407
  * failure shows the standard notice. \`confirm\` asks first. \`to\` draws a link that looks like a button.
1439
- * A \`type="submit"\` button inside a <form action> shows the form's pending state.
1408
+ * A \`type="submit"\` button inside a <form action> shows the form's pending state; \`busy\` shows any other.
1440
1409
  */
1441
1410
  export default function Button({
1442
1411
  children,
1443
1412
  variant = "secondary",
1444
1413
  size,
1445
- action,
1414
+ action: given,
1415
+ onClick,
1446
1416
  confirm: question,
1447
1417
  to,
1448
1418
  type = "button",
1449
1419
  disabled,
1420
+ busy: pending,
1450
1421
  label,
1451
1422
  title,
1452
1423
  }: {
@@ -1455,19 +1426,24 @@ export default function Button({
1455
1426
  size?: "sm";
1456
1427
  /** What a click does; a returned promise keeps the button busy until it settles. */
1457
1428
  action?: () => unknown;
1429
+ /** The same as action, under the name a button's handler usually has. */
1430
+ onClick?: () => unknown;
1458
1431
  /** A question the person confirms before \`action\` runs, such as "Delete this order?". */
1459
1432
  confirm?: string;
1460
1433
  /** A route of this Site: the button is a link. */
1461
1434
  to?: string;
1462
1435
  type?: "button" | "submit";
1463
1436
  disabled?: boolean;
1437
+ /** Busy, as while its own action runs: a Form's submit button while the form's action does. */
1438
+ busy?: boolean;
1464
1439
  /** The accessible name, for a button whose children are only a symbol. */
1465
1440
  label?: string;
1466
1441
  title?: string;
1467
1442
  }) {
1443
+ const action = given ?? onClick;
1468
1444
  const [running, start] = useTransition();
1469
1445
  const form = useFormStatus();
1470
- const busy = running || (type === "submit" && form.pending);
1446
+ const busy = running || pending === true || (type === "submit" && form.pending);
1471
1447
  const className = ["btn", variant === "secondary" ? "" : variant, size ?? ""].join(" ").trim();
1472
1448
  if (to)
1473
1449
  return (
@@ -2098,7 +2074,7 @@ export default function Panel({
2098
2074
  `,
2099
2075
  "components/SearchBox.tsx": `/**
2100
2076
  * A labelled search input with a clear button; Escape clears it too. Filter in the query with
2101
- * { col: { like: \`%\${q}%\` } }, and debounce the value (useDebounced) when every keystroke would query.
2077
+ * { col: { contains: q } }, and debounce the value (useDebounced) when every keystroke would query.
2102
2078
  */
2103
2079
  export default function SearchBox({
2104
2080
  value,
@@ -2253,6 +2229,429 @@ export default function Yes({ value }: { value: boolean | null | undefined }) {
2253
2229
  if (value === null || value === undefined) return <span className="muted">—</span>;
2254
2230
  return <span>{value ? "Yes" : "No"}</span>;
2255
2231
  }
2232
+ `,
2233
+ "components/Board.tsx": `import type { ReactNode } from "react";
2234
+
2235
+ /**
2236
+ * Columns of cards side by side, one per team, stage or status, wrapping as the page narrows: put BoardColumn
2237
+ * inside, and Card inside each. For a table of rows use DataTable.
2238
+ */
2239
+ export default function Board({ children }: { children: ReactNode }) {
2240
+ return <div className="board">{children}</div>;
2241
+ }
2242
+ `,
2243
+ "components/BoardColumn.tsx": `import type { ReactNode } from "react";
2244
+
2245
+ /**
2246
+ * One column of a Board: a title, how many it holds, an optional line under the title and a control at its
2247
+ * end (aside), then its Cards. With count 0 it shows empty instead of its children.
2248
+ */
2249
+ export default function BoardColumn({
2250
+ title,
2251
+ count,
2252
+ hint,
2253
+ aside,
2254
+ empty = "Nothing here.",
2255
+ children,
2256
+ }: {
2257
+ title: string;
2258
+ count?: number;
2259
+ hint?: ReactNode;
2260
+ aside?: ReactNode;
2261
+ empty?: string;
2262
+ children?: ReactNode;
2263
+ }) {
2264
+ return (
2265
+ <section className="board-column">
2266
+ <header className="board-head">
2267
+ <div className="board-title">
2268
+ <h3>{title}</h3>
2269
+ {count === undefined ? null : <span className="board-count">{count}</span>}
2270
+ </div>
2271
+ {aside}
2272
+ </header>
2273
+ {hint ? <p className="board-hint">{hint}</p> : null}
2274
+ <div className="board-cards">
2275
+ {count === 0 ? <p className="board-empty">{empty}</p> : children}
2276
+ </div>
2277
+ </section>
2278
+ );
2279
+ }
2280
+ `,
2281
+ "components/Card.tsx": `import type { ReactNode } from "react";
2282
+ import { Link } from "@ezship/react";
2283
+
2284
+ /**
2285
+ * One item of a BoardColumn or a list of cards: a title, a Badge beside it (aside), a muted line (meta) and
2286
+ * anything else under them. With to, the whole card is a link to that route, so it holds no button or input.
2287
+ */
2288
+ export default function Card({
2289
+ title,
2290
+ meta,
2291
+ aside,
2292
+ to,
2293
+ children,
2294
+ }: {
2295
+ title: ReactNode;
2296
+ meta?: ReactNode;
2297
+ aside?: ReactNode;
2298
+ to?: string;
2299
+ children?: ReactNode;
2300
+ }) {
2301
+ const body = (
2302
+ <>
2303
+ <div className="card-head">
2304
+ <span className="card-title">{title}</span>
2305
+ {aside}
2306
+ </div>
2307
+ {meta ? <div className="card-meta">{meta}</div> : null}
2308
+ {children}
2309
+ </>
2310
+ );
2311
+ return to ? (
2312
+ <Link to={to} className="card">
2313
+ {body}
2314
+ </Link>
2315
+ ) : (
2316
+ <div className="card">{body}</div>
2317
+ );
2318
+ }
2319
+ `,
2320
+ "components/Checkbox.tsx": `import type { ReactNode } from "react";
2321
+
2322
+ /** A labelled checkbox: checked is its value, and onChange answers the new one. */
2323
+ export default function Checkbox({
2324
+ label,
2325
+ checked,
2326
+ onChange,
2327
+ disabled,
2328
+ }: {
2329
+ label: ReactNode;
2330
+ checked: boolean;
2331
+ onChange: (checked: boolean) => void;
2332
+ disabled?: boolean;
2333
+ }) {
2334
+ return (
2335
+ <label className="field check">
2336
+ <input
2337
+ type="checkbox"
2338
+ checked={checked}
2339
+ disabled={disabled}
2340
+ onChange={(e) => onChange(e.target.checked)}
2341
+ />
2342
+ <span>{label}</span>
2343
+ </label>
2344
+ );
2345
+ }
2346
+ `,
2347
+ "components/DateInput.tsx": `import type { ReactNode } from "react";
2348
+ import type { DateString } from "@ezship/react";
2349
+ import Field from "./Field";
2350
+
2351
+ /** A labelled date input for a DATE column: value is a DateString or null, and onChange answers the same. */
2352
+ export default function DateInput({
2353
+ label,
2354
+ value,
2355
+ onChange,
2356
+ hint,
2357
+ error,
2358
+ required,
2359
+ disabled,
2360
+ min,
2361
+ max,
2362
+ }: {
2363
+ label: string;
2364
+ value: DateString | null;
2365
+ onChange: (value: DateString | null) => void;
2366
+ hint?: ReactNode;
2367
+ error?: string | null;
2368
+ required?: boolean;
2369
+ disabled?: boolean;
2370
+ min?: DateString;
2371
+ max?: DateString;
2372
+ }) {
2373
+ return (
2374
+ <Field label={label} hint={hint} error={error} required={required}>
2375
+ <input
2376
+ type="date"
2377
+ value={value ?? ""}
2378
+ min={min}
2379
+ max={max}
2380
+ disabled={disabled}
2381
+ aria-invalid={error ? true : undefined}
2382
+ aria-required={required ? true : undefined}
2383
+ onChange={(e) => onChange(e.target.value === "" ? null : e.target.value)}
2384
+ />
2385
+ </Field>
2386
+ );
2387
+ }
2388
+ `,
2389
+ "components/Form.tsx": `import { startTransition, useActionState, type ReactNode } from "react";
2390
+ import { attempt } from "@ezship/react";
2391
+ import Button from "./Button";
2392
+ import Notice from "./Notice";
2393
+
2394
+ /**
2395
+ * A form that runs action when it is submitted: a server function call, or a db write. Put the inputs inside
2396
+ * (TextInput, NumberInput, SelectInput, DateInput, TextArea, Checkbox, a Field). While action runs the submit
2397
+ * button is busy; what it throws (a failed check, a refused write, a function's error) shows above the fields
2398
+ * and the form stays as it was. columns 2 lays the fields in two columns on a wide screen, a TextArea across
2399
+ * both. onCancel adds a Cancel button. Inside a Dialog, give the Dialog no footer.
2400
+ */
2401
+ export default function Form({
2402
+ action,
2403
+ submit = "Save",
2404
+ onCancel,
2405
+ columns = 1,
2406
+ children,
2407
+ }: {
2408
+ /** What Submit does; throw an Error to refuse, with the message to show. */
2409
+ action: () => unknown;
2410
+ /** The submit button's words. */
2411
+ submit?: string;
2412
+ onCancel?: () => void;
2413
+ columns?: 1 | 2;
2414
+ children: ReactNode;
2415
+ }) {
2416
+ const [error, save, pending] = useActionState(
2417
+ attempt(async () => {
2418
+ await action();
2419
+ }),
2420
+ null,
2421
+ );
2422
+ // Submitted from onSubmit, not <form action>: React resets a form after its action, which would show a
2423
+ // controlled select or checkbox at its first value while its state keeps the chosen one.
2424
+ return (
2425
+ <form
2426
+ className="form"
2427
+ noValidate
2428
+ onSubmit={(e) => {
2429
+ e.preventDefault();
2430
+ if (!pending) startTransition(save);
2431
+ }}
2432
+ >
2433
+ {error ? <Notice tone="danger">{error}</Notice> : null}
2434
+ <div className={columns === 2 ? "form-fields two" : "form-fields"}>{children}</div>
2435
+ <div className="form-actions">
2436
+ {onCancel ? <Button action={onCancel}>Cancel</Button> : null}
2437
+ <Button type="submit" variant="primary" busy={pending}>
2438
+ {submit}
2439
+ </Button>
2440
+ </div>
2441
+ </form>
2442
+ );
2443
+ }
2444
+ `,
2445
+ "components/NumberInput.tsx": `import type { ReactNode } from "react";
2446
+ import Field from "./Field";
2447
+
2448
+ /**
2449
+ * A labelled number input for an INTEGER or REAL column: value is a number or null (empty), and onChange
2450
+ * answers the same, never text. For MONEY keep a text input and toCents.
2451
+ */
2452
+ export default function NumberInput({
2453
+ label,
2454
+ value,
2455
+ onChange,
2456
+ hint,
2457
+ error,
2458
+ required,
2459
+ disabled,
2460
+ min,
2461
+ max,
2462
+ step,
2463
+ placeholder,
2464
+ }: {
2465
+ label: string;
2466
+ value: number | null;
2467
+ onChange: (value: number | null) => void;
2468
+ hint?: ReactNode;
2469
+ error?: string | null;
2470
+ required?: boolean;
2471
+ disabled?: boolean;
2472
+ min?: number;
2473
+ max?: number;
2474
+ step?: number;
2475
+ placeholder?: string;
2476
+ }) {
2477
+ return (
2478
+ <Field label={label} hint={hint} error={error} required={required}>
2479
+ <input
2480
+ type="number"
2481
+ inputMode="decimal"
2482
+ value={value ?? ""}
2483
+ min={min}
2484
+ max={max}
2485
+ step={step}
2486
+ placeholder={placeholder}
2487
+ disabled={disabled}
2488
+ aria-invalid={error ? true : undefined}
2489
+ aria-required={required ? true : undefined}
2490
+ onChange={(e) => {
2491
+ const next = e.target.value === "" ? null : Number(e.target.value);
2492
+ onChange(next === null || Number.isNaN(next) ? null : next);
2493
+ }}
2494
+ />
2495
+ </Field>
2496
+ );
2497
+ }
2498
+ `,
2499
+ "components/SelectInput.tsx": `import type { ReactNode } from "react";
2500
+ import Field from "./Field";
2501
+
2502
+ /**
2503
+ * A labelled choice from a few options: each a string, or a value with its label. value is the chosen one or
2504
+ * null, shown as placeholder. For a CHECK column pass schema.column(table, column)?.values ?? []; for a
2505
+ * reference to another Table use RefPicker.
2506
+ */
2507
+ export default function SelectInput({
2508
+ label,
2509
+ value,
2510
+ onChange,
2511
+ options,
2512
+ placeholder = "Choose…",
2513
+ hint,
2514
+ error,
2515
+ required,
2516
+ disabled,
2517
+ }: {
2518
+ label: string;
2519
+ value: string | null;
2520
+ onChange: (value: string | null) => void;
2521
+ options: readonly (string | { value: string; label: string })[];
2522
+ placeholder?: string;
2523
+ hint?: ReactNode;
2524
+ error?: string | null;
2525
+ required?: boolean;
2526
+ disabled?: boolean;
2527
+ }) {
2528
+ return (
2529
+ <Field label={label} hint={hint} error={error} required={required}>
2530
+ <select
2531
+ value={value ?? ""}
2532
+ disabled={disabled}
2533
+ aria-invalid={error ? true : undefined}
2534
+ aria-required={required ? true : undefined}
2535
+ onChange={(e) => onChange(e.target.value === "" ? null : e.target.value)}
2536
+ >
2537
+ <option value="">{placeholder}</option>
2538
+ {options.map((o) => {
2539
+ const option = typeof o === "string" ? { value: o, label: o } : o;
2540
+ return (
2541
+ <option key={option.value} value={option.value}>
2542
+ {option.label}
2543
+ </option>
2544
+ );
2545
+ })}
2546
+ </select>
2547
+ </Field>
2548
+ );
2549
+ }
2550
+ `,
2551
+ "components/Stats.tsx": `import type { ReactNode } from "react";
2552
+
2553
+ /** A row of Stat tiles, all one width, wrapping as the page narrows: put Stat inside. */
2554
+ export default function Stats({ children }: { children: ReactNode }) {
2555
+ return <div className="stats">{children}</div>;
2556
+ }
2557
+ `,
2558
+ "components/TextArea.tsx": `import type { ReactNode } from "react";
2559
+ import Field from "./Field";
2560
+
2561
+ /** A labelled multi-line text input: value is its text, and onChange answers the new text. */
2562
+ export default function TextArea({
2563
+ label,
2564
+ value,
2565
+ onChange,
2566
+ hint,
2567
+ error,
2568
+ required,
2569
+ disabled,
2570
+ placeholder,
2571
+ rows = 3,
2572
+ }: {
2573
+ label: string;
2574
+ value: string;
2575
+ onChange: (value: string) => void;
2576
+ hint?: ReactNode;
2577
+ error?: string | null;
2578
+ required?: boolean;
2579
+ disabled?: boolean;
2580
+ placeholder?: string;
2581
+ rows?: number;
2582
+ }) {
2583
+ return (
2584
+ <Field label={label} hint={hint} error={error} required={required}>
2585
+ <textarea
2586
+ value={value}
2587
+ rows={rows}
2588
+ placeholder={placeholder}
2589
+ disabled={disabled}
2590
+ aria-invalid={error ? true : undefined}
2591
+ aria-required={required ? true : undefined}
2592
+ onChange={(e) => onChange(e.target.value)}
2593
+ />
2594
+ </Field>
2595
+ );
2596
+ }
2597
+ `,
2598
+ "components/TextInput.tsx": `import type { ReactNode } from "react";
2599
+ import Field from "./Field";
2600
+
2601
+ /** A labelled one-line text input: value is its text, and onChange answers the new text. */
2602
+ export default function TextInput({
2603
+ label,
2604
+ value,
2605
+ onChange,
2606
+ hint,
2607
+ error,
2608
+ required,
2609
+ disabled,
2610
+ placeholder,
2611
+ type = "text",
2612
+ autoFocus,
2613
+ }: {
2614
+ label: string;
2615
+ value: string;
2616
+ onChange: (value: string) => void;
2617
+ hint?: ReactNode;
2618
+ error?: string | null;
2619
+ required?: boolean;
2620
+ disabled?: boolean;
2621
+ placeholder?: string;
2622
+ type?: "text" | "email" | "tel" | "url" | "password";
2623
+ autoFocus?: boolean;
2624
+ }) {
2625
+ return (
2626
+ <Field label={label} hint={hint} error={error} required={required}>
2627
+ <input
2628
+ type={type}
2629
+ value={value}
2630
+ placeholder={placeholder}
2631
+ disabled={disabled}
2632
+ autoFocus={autoFocus}
2633
+ aria-invalid={error ? true : undefined}
2634
+ aria-required={required ? true : undefined}
2635
+ onChange={(e) => onChange(e.target.value)}
2636
+ />
2637
+ </Field>
2638
+ );
2639
+ }
2640
+ `,
2641
+ "components/Toolbar.tsx": `import type { ReactNode } from "react";
2642
+
2643
+ /**
2644
+ * The controls above a list, in one row that wraps: a SearchBox, FilterChips or a select as children, and
2645
+ * aside (a button, a count) at the far end. First inside a Panel it draws as the Panel's top strip.
2646
+ */
2647
+ export default function Toolbar({ children, aside }: { children: ReactNode; aside?: ReactNode }) {
2648
+ return (
2649
+ <div className="toolbar">
2650
+ {children}
2651
+ {aside ? <div className="toolbar-aside">{aside}</div> : null}
2652
+ </div>
2653
+ );
2654
+ }
2256
2655
  `,
2257
2656
  [CONSTANTS_FILE]: `/** The Instance's name as the starter Shell's top bar shows it. */
2258
2657
  export const BRAND = "My company";
@@ -2286,8 +2685,10 @@ export default function Shell({ children }: { children: ReactNode }) {
2286
2685
  // ---- the structural Rules: what push can check with no parser ----------------------------------------------
2287
2686
  //
2288
2687
  // The full Rules (which parts of React, banned globals, constant shapes) need a parser and run on `bun lint` in
2289
- // the Pipeline (docs/adr/0121, 0122); deploy and `ez check` run them on the platform. This subset is regex over import
2290
- // statements and export lines, enough for push to refuse a Working Copy that could never deploy.
2688
+ // the Pipeline (docs/adr/0236, 0237); deploy and `ez check` run them on the platform. This subset is regex over import
2689
+ // statements and export lines, enough for push to refuse a Working Copy that could never deploy. Anything that
2690
+ // must tell code from text (a dynamic `import()`, `import.meta`) is a parser Rule, never a regex here: page
2691
+ // text, strings and comments say "import (" too.
2291
2692
 
2292
2693
  /** @typedef {{ file: string, range: { start: { line: number, character: number }, end: { line: number, character: number } }, severity: 1, code: string, message: string }} Diagnostic */
2293
2694
 
@@ -2296,11 +2697,10 @@ export default function Shell({ children }: { children: ReactNode }) {
2296
2697
  // `export default function` and JSX text such as `from "the list"` from matching.
2297
2698
  const IMPORT_RE =
2298
2699
  /^[ \t]*(?:import|export)\s+(type\s+)?(?:(?:\*\s+as\s+\w+|\{[^}'"]*\}|\w+)(?:\s*,\s*(?:\{[^}'"]*\}|\*\s+as\s+\w+))?\s+from\s+)?["']([^"'\n]+)["']/gm;
2299
- const DYNAMIC_IMPORT_RE = /\bimport\s*\(/g;
2300
2700
  const DEFAULT_EXPORT_RE = /^export\s+default\s+function\s+([A-Za-z_$][\w$]*)/m;
2301
2701
  const OTHER_EXPORT_RE = /^export\s+(?!default\s)/m;
2302
2702
  const APP_OTHER_EXPORT_RE = /^export\s+(?!default\s|type\s+Provided\s*=)/m;
2303
- /** A page may also say who opens it (docs/adr/0098): `export const access = "group(<name>)"`. */
2703
+ /** A page may also say who opens it (docs/adr/0225): `export const access = "group(<name>)"`. */
2304
2704
  const PAGE_OTHER_EXPORT_RE = /^export\s+(?!default\s|const\s+access\s*=)/m;
2305
2705
  const PAGE_ACCESS_RE = /^export\s+const\s+access\s*=\s*(.*)$/m;
2306
2706
  const PAGE_ACCESS_LITERAL_RE = /^(["'])([^"'\\]*)\1\s*;?\s*$/;
@@ -2353,23 +2753,26 @@ function resolveRelative(from, specifier) {
2353
2753
  return parts.join("/");
2354
2754
  }
2355
2755
 
2356
- const IMPORT_SHAPE = `Site code imports only react, @ezship/react, ${SITE_PACKAGES.join(", ")}, global/<Name>, global/documents/<Name>, global/hooks/use<Name>, global/constants, global/lib/<name>, ./constants, ./components/<Name>, ./hooks/use<Name>, ./functions/<name>, ./local/<name> (../constants, ../components/<Name>, ../hooks/use<Name>, ../functions/<name> and ../local/<name> from a page, component or hook), and \`import type\` from global/db/types (no extensions).`;
2357
- /** A component of the Instance's Global Workspace. Whether it exists is the platform's check, not this one. */
2358
- const GLOBAL_RE = /^global\/[A-Z][A-Za-z0-9]*$/;
2359
- /** A Document of the Global Workspace (docs/adr/0105): Site code imports its default, a typed descriptor. */
2756
+ const IMPORT_SHAPE = `Site code imports only react, @ezship/react, ${SITE_PACKAGES.join(", ")}, global/<Name>, global/documents/<Name>, global/hooks/use<Name>, global/constants, global/lib/<name>, ./constants, ./components/<Name>, ./hooks/use<Name>, ./lib/<name>, ./functions/<name>, ./local/<name> (../constants, ../components/<Name>, ../hooks/use<Name>, ../lib/<name>, ../functions/<name> and ../local/<name> from a page, component or hook), and \`import type\` from global/db/types (no extensions).`;
2757
+ /**
2758
+ * A component of the Instance's Global Workspace, by its short name or by its path (`global/components/<Name>`,
2759
+ * docs/adr/0204). Whether it exists is the platform's check, not this one.
2760
+ */
2761
+ const GLOBAL_RE = /^global\/(?:components\/)?[A-Z][A-Za-z0-9]*$/;
2762
+ /** A Document of the Global Workspace (docs/adr/0233): Site code imports its default, a typed descriptor. */
2360
2763
  const GLOBAL_DOCUMENT_RE = /^global\/documents\/[A-Z][A-Za-z0-9]*$/;
2361
2764
  /** Why a `global/lib/...` specifier is malformed, or null. Whether the module exists is the type check's. */
2362
2765
  const libSpecifierError = (/** @type {string} */ specifier) =>
2363
2766
  libModuleName(specifier.slice("global/".length) + ".ts")
2364
2767
  ? null
2365
2768
  : `"${specifier}": a Global lib module is imported as global/lib/<name> (global/lib/accounting), no extension.`;
2366
- /** Why a `global/hooks/...` specifier is malformed, or null (ADR 0091). */
2769
+ /** Why a `global/hooks/...` specifier is malformed, or null (ADR 0209). */
2367
2770
  const hookSpecifierError = (/** @type {string} */ specifier) =>
2368
2771
  hookName(specifier.slice("global/".length) + ".ts")
2369
2772
  ? null
2370
2773
  : `"${specifier}": a Global hook is imported as global/hooks/use<Name> (global/hooks/useOpenOrders), no extension.`;
2371
2774
  const GLOBAL_SPECIFIER_HINT = (/** @type {string} */ specifier) =>
2372
- `"${specifier}": use global/<Name> for a PascalCase component, global/documents/<Name> for a Document, global/hooks/use<Name> for a custom hook, global/lib/<name> for shared logic or global/constants for plain values, no extension.`;
2775
+ `"${specifier}": use global/<Name> (or global/components/<Name>) for a PascalCase component, global/documents/<Name> for a Document, global/hooks/use<Name> for a custom hook, global/lib/<name> for shared logic or global/constants for plain values, no extension.`;
2373
2776
 
2374
2777
  /**
2375
2778
  * Why `path` may not import `specifier`, or null.
@@ -2387,10 +2790,46 @@ export function importError(path, specifier, typeOnly, files) {
2387
2790
  if (target && localFunctionName(target + ".ts") && target + ".ts" in files) return null;
2388
2791
  return `${specifier}: local functions import @ezship/react/local, node:* built-ins, constants, sibling local functions, and type-only global/db/types.`;
2389
2792
  }
2793
+ // A Site's own lib module (ADR 0209): a Global lib module's imports, and the constants.
2794
+ if (libModuleName(path)) {
2795
+ if (specifier === "global/constants") return null;
2796
+ if (
2797
+ specifier === "@ezship/react/server" ||
2798
+ specifier === "@ezship/react" ||
2799
+ specifier === "global/db/types"
2800
+ )
2801
+ return typeOnly
2802
+ ? null
2803
+ : `"${specifier}": a lib module imports only types from it; use import type.`;
2804
+ if (specifier.startsWith("global/lib/")) return libSpecifierError(specifier);
2805
+ const target =
2806
+ specifier.startsWith("./") || specifier.startsWith("../")
2807
+ ? resolveRelative(path, specifier)
2808
+ : null;
2809
+ if (target === "constants") return null;
2810
+ if (target && libModuleName(target + ".ts")) {
2811
+ if (target + ".ts" === path) return `"${specifier}": a module cannot import itself.`;
2812
+ return target + ".ts" in files
2813
+ ? null
2814
+ : `"${specifier}": there is no ${target}.ts in the working copy.`;
2815
+ }
2816
+ return `"${specifier}" cannot be imported. ${SITE_LIB_IMPORT_SHAPE}`;
2817
+ }
2818
+ // What a Site's own lib module is to its importers: a file of the working copy.
2819
+ const siteLib = () => {
2820
+ const target =
2821
+ specifier.startsWith("./") || specifier.startsWith("../")
2822
+ ? resolveRelative(path, specifier)
2823
+ : null;
2824
+ if (!target || !libModuleName(target + ".ts")) return undefined;
2825
+ return target + ".ts" in files
2826
+ ? null
2827
+ : `"${specifier}": there is no ${target}.ts in the working copy.`;
2828
+ };
2390
2829
  const importedListener = specifier.startsWith(".") ? resolveRelative(path, specifier) : null;
2391
2830
  if (importedListener && listenerName(importedListener + ".ts"))
2392
2831
  return `${specifier}: listeners are never imported; ${LISTENERS_FILE} delivers events to them.`;
2393
- // A Listener (ADR 0092) imports what a server function imports, but no Document.
2832
+ // A Listener (ADR 0231) imports what a server function imports, but no Document.
2394
2833
  if (listenerName(path)) {
2395
2834
  if (specifier === "@ezship/react/server" || specifier === "global/constants") return null;
2396
2835
  if (specifier === "global/db/types" && typeOnly) return null;
@@ -2398,7 +2837,9 @@ export function importError(path, specifier, typeOnly, files) {
2398
2837
  const target = resolveRelative(path, specifier);
2399
2838
  if (target === "constants") return null;
2400
2839
  if (target && functionName(target + ".ts") && target + ".ts" in files) return null;
2401
- return `${specifier}: listeners import @ezship/react/server, constants, sibling functions, global/lib/<name> modules and type-only global/db/types.`;
2840
+ const lib = siteLib();
2841
+ if (lib !== undefined) return lib;
2842
+ return `${specifier}: listeners import @ezship/react/server, constants, sibling functions, lib modules (../lib/<name>, global/lib/<name>) and type-only global/db/types.`;
2402
2843
  }
2403
2844
  if (functionName(path)) {
2404
2845
  if (specifier === "@ezship/react/server" || specifier === "global/constants") return null;
@@ -2408,7 +2849,9 @@ export function importError(path, specifier, typeOnly, files) {
2408
2849
  const target = resolveRelative(path, specifier);
2409
2850
  if (target === "constants") return null;
2410
2851
  if (target && functionName(target + ".ts") && target + ".ts" in files) return null;
2411
- return `${specifier}: server functions import @ezship/react/server, constants, sibling functions, global/lib/<name> modules, global/documents/<Name> and type-only global/db/types.`;
2852
+ const lib = siteLib();
2853
+ if (lib !== undefined) return lib;
2854
+ return `${specifier}: server functions import @ezship/react/server, constants, sibling functions, lib modules (../lib/<name>, global/lib/<name>), global/documents/<Name> and type-only global/db/types.`;
2412
2855
  }
2413
2856
  if (path === CONSTANTS_FILE)
2414
2857
  return `${CONSTANTS_FILE} imports nothing: it holds plain values only.`;
@@ -2429,7 +2872,7 @@ export function importError(path, specifier, typeOnly, files) {
2429
2872
  return `"${specifier}": write the import without the extension. ${IMPORT_SHAPE}`;
2430
2873
  const target = resolveRelative(path, specifier);
2431
2874
  if (target === "constants") return null;
2432
- // ADR 0088: the type of the values App.tsx provides, for useProvided<Provided>().
2875
+ // ADR 0214: the type of the values App.tsx provides, for useProvided<Provided>().
2433
2876
  if (target === "App" && path !== MAIN_FILE)
2434
2877
  return typeOnly
2435
2878
  ? null
@@ -2445,8 +2888,6 @@ export function importError(path, specifier, typeOnly, files) {
2445
2888
  return `"${specifier}" points inside pages/; from a page, write "../${meant}".`;
2446
2889
  return `"${specifier}": pages are never imported; the router renders them by route. Shared markup is a component.`;
2447
2890
  }
2448
- if (target === "db/types")
2449
- return `"${specifier}" moved to "global/db/types"; update this type import.`;
2450
2891
  if (target && componentName(target + ".tsx")) {
2451
2892
  if (target + ".tsx" === path) return `"${specifier}": a component cannot import itself.`;
2452
2893
  return target + ".tsx" in files
@@ -2459,11 +2900,14 @@ export function importError(path, specifier, typeOnly, files) {
2459
2900
  ? null
2460
2901
  : `"${specifier}": there is no ${target}.ts in the working copy.`;
2461
2902
  }
2903
+ const lib = siteLib();
2904
+ if (lib !== undefined) return lib;
2462
2905
  return `"${specifier}" cannot be imported. ${IMPORT_SHAPE}`;
2463
2906
  }
2464
2907
 
2465
2908
  const DOCUMENT_IMPORT_SHAPE = `A Document imports only @ezship/react/pdf, global/constants (or ../constants), type-only global/db/types and sibling Documents (./<Name>).`;
2466
2909
  const GLOBAL_IMPORT_SHAPE = `Global Workspace code imports only react, @ezship/react, ${SITE_PACKAGES.join(", ")}, type-only global/db/types, global/constants (or ./constants from ${SHELL_FILE}, ../constants from a component or hook), global/lib/<name> modules, global hooks (global/hooks/use<Name>, or ../hooks/use<Name> from a component, ./use<Name> from a hook and ./hooks/use<Name> from ${SHELL_FILE}) and other global components (global/<Name>, or ./<Name> from a component and ./components/<Name> from ${SHELL_FILE}).`;
2910
+ const SITE_LIB_IMPORT_SHAPE = `A Site's lib module imports only other lib modules (./<name> or global/lib/<name>), constants (../constants, global/constants) and types: \`import type\` from @ezship/react, @ezship/react/server and global/db/types. No packages, no network, no components or hooks.`;
2467
2911
  const LIB_IMPORT_SHAPE = `A lib module imports only other lib modules (global/lib/<name> or ./<name>) and types: \`import type\` from @ezship/react/server and global/db/types. No packages, no network, no components or constants.`;
2468
2912
 
2469
2913
  /**
@@ -2486,7 +2930,7 @@ function libTarget(path, specifier) {
2486
2930
  export function globalImportError(path, specifier, files, typeOnly = false) {
2487
2931
  if (path === CONSTANTS_FILE)
2488
2932
  return `${CONSTANTS_FILE} imports nothing: it holds plain values only.`;
2489
- // ADR 0088: the declaration holds types and its defaults; it names row types and the Framework's brands.
2933
+ // ADR 0214: the declaration holds types and its defaults; it names row types and the Framework's brands.
2490
2934
  if (path === SESSION_FILE)
2491
2935
  return (specifier === "@ezship/react" ||
2492
2936
  specifier === "global/db/types" ||
@@ -2515,7 +2959,7 @@ export function globalImportError(path, specifier, files, typeOnly = false) {
2515
2959
  ? null
2516
2960
  : `"${specifier}": there is no ${lib}.ts in the Global Workspace.`;
2517
2961
  }
2518
- // A scheduled job (ADR 0136) imports what a Table rule imports; nothing imports a job.
2962
+ // A scheduled job (ADR 0230) imports what a Table rule imports; nothing imports a job.
2519
2963
  if (jobName(path)) {
2520
2964
  if (specifier === "@ezship/react/server") return null;
2521
2965
  if (specifier === "global/constants" || resolveRelative(path, specifier) === "constants")
@@ -2527,7 +2971,7 @@ export function globalImportError(path, specifier, files, typeOnly = false) {
2527
2971
  const importedJob = specifier.startsWith(".") ? resolveRelative(path, specifier) : null;
2528
2972
  if (importedJob && jobName(importedJob + ".ts"))
2529
2973
  return `"${specifier}": jobs are never imported; ${SCHEDULES_FILE} runs them.`;
2530
- // A Table rule (docs/adr/0099) or a workflow (docs/adr/0103) imports what server code may.
2974
+ // A Table rule (docs/adr/0226) or a workflow (docs/adr/0227) imports what server code may.
2531
2975
  if (liveCodeTable(path)) {
2532
2976
  if (specifier === "@ezship/react/server") return null;
2533
2977
  if (specifier === "global/constants" || resolveRelative(path, specifier) === "constants")
@@ -2600,7 +3044,7 @@ export function checkGlobalStructure(files) {
2600
3044
  });
2601
3045
  const context = contextError(files[CONTEXT_FILE]);
2602
3046
  if (context) top(CONTEXT_FILE, "context", context);
2603
- // The Instance's schedules (ADR 0136), checked as a Push checks them.
3047
+ // The Instance's schedules (ADR 0230), checked as a Push checks them.
2604
3048
  if (SCHEDULES_FILE in files)
2605
3049
  for (const error of parseSchedules(files[SCHEDULES_FILE], files).errors)
2606
3050
  top(SCHEDULES_FILE, "schedules", error);
@@ -2618,14 +3062,14 @@ export function checkGlobalStructure(files) {
2618
3062
  const declared = parseSessionDeclaration(source);
2619
3063
  if ("error" in declared) top(path, "session-shape", declared.error);
2620
3064
  }
2621
- // A rules or workflow file names a Table of the schema beside it (docs/adr/0099, 0103).
3065
+ // A rules or workflow file names a Table of the schema beside it (docs/adr/0226, 0227).
2622
3066
  const ruled = liveCodeTable(path);
2623
3067
  if (ruled) {
2624
3068
  const schema = parseGlobalSchema(files[SCHEMA_FILE] ?? "");
2625
3069
  if (!("error" in schema) && !Object.hasOwn(schema.tables, ruled))
2626
3070
  top(path, "path", `${path}: no Table "${ruled}" in ${SCHEMA_FILE}.`);
2627
3071
  }
2628
- // A workflow's names are read from the file without running it, to type its column (docs/adr/0103).
3072
+ // A workflow's names are read from the file without running it, to type its column (docs/adr/0227).
2629
3073
  if (workflowTableName(path)) {
2630
3074
  const shape = readWorkflow(source);
2631
3075
  if ("error" in shape)
@@ -2639,8 +3083,15 @@ export function checkGlobalStructure(files) {
2639
3083
  code: "workflow-shape",
2640
3084
  message: `${path}: ${shape.error}.`,
2641
3085
  });
3086
+ else {
3087
+ // The names a Push would refuse (docs/adr/0227) are refused here first: the check is the gate.
3088
+ const schema = parseGlobalSchema(files[SCHEMA_FILE] ?? "");
3089
+ const table = workflowTableName(path);
3090
+ const wrong = "error" in schema || !table ? null : checkWorkflowNames(table, shape, schema);
3091
+ if (wrong) top(path, "workflow-shape", wrong);
3092
+ }
2642
3093
  }
2643
- // Access rules (docs/adr/0098) are checked against the schema beside them, as a Push checks them.
3094
+ // Access rules (docs/adr/0225) are checked against the schema beside them, as a Push checks them.
2644
3095
  if (path === ACCESS_FILE) {
2645
3096
  const schema = parseGlobalSchema(files[SCHEMA_FILE] ?? "");
2646
3097
  const checked = "error" in schema ? null : checkAccess(source, schema);
@@ -2670,17 +3121,6 @@ export function checkGlobalStructure(files) {
2670
3121
  const why = globalImportError(path, m[2], files, m[1] !== undefined);
2671
3122
  if (why) out.push(diag(path, source, m.index, m[0].length, "import", why));
2672
3123
  }
2673
- for (const m of source.matchAll(DYNAMIC_IMPORT_RE))
2674
- out.push(
2675
- diag(
2676
- path,
2677
- source,
2678
- m.index,
2679
- m[0].length,
2680
- "dynamic-import",
2681
- "Global Workspace code never loads code at runtime; import at the top of the file.",
2682
- ),
2683
- );
2684
3124
  // A job's shape (one default job() call) is the Pipeline's `function-export` Rule, as a rule's is.
2685
3125
  if (
2686
3126
  path === CONSTANTS_FILE ||
@@ -2784,7 +3224,7 @@ export function checkStructure(files) {
2784
3224
  "entry-missing",
2785
3225
  `The working copy has no ${MAIN_FILE}; the app needs one at the root.`,
2786
3226
  );
2787
- // ADR 0092: listeners.json, and the listeners/ files nothing delivers to (a warning).
3227
+ // ADR 0231: listeners.json, and the listeners/ files nothing delivers to (a warning).
2788
3228
  const listeners =
2789
3229
  LISTENERS_FILE in files
2790
3230
  ? parseListeners(files[LISTENERS_FILE], files)
@@ -2809,17 +3249,6 @@ export function checkStructure(files) {
2809
3249
  const why = importError(path, m[2], m[1] !== undefined, files);
2810
3250
  if (why) out.push(diag(path, source, m.index, m[0].length, "import", why));
2811
3251
  }
2812
- for (const m of source.matchAll(DYNAMIC_IMPORT_RE))
2813
- out.push(
2814
- diag(
2815
- path,
2816
- source,
2817
- m.index,
2818
- m[0].length,
2819
- "dynamic-import",
2820
- "Site code never loads code at runtime; import at the top of the file.",
2821
- ),
2822
- );
2823
3252
  // App.tsx, components and hooks must default-export the named function; a page default-exports any name.
2824
3253
  const hook = hookName(path);
2825
3254
  const want = path === MAIN_FILE ? "App" : (hook ?? componentName(path));
@@ -2847,7 +3276,7 @@ export function checkStructure(files) {
2847
3276
  `${path} must export ${want}, not ${d[1]}: the file name is the ${kind} name.`,
2848
3277
  ),
2849
3278
  );
2850
- // ADR 0098: a page's access is a literal row-free condition the Framework checks before it renders.
3279
+ // ADR 0225: a page's access is a literal row-free condition the Framework checks before it renders.
2851
3280
  const access = isPage ? PAGE_ACCESS_RE.exec(source) : null;
2852
3281
  if (access) {
2853
3282
  const literal = PAGE_ACCESS_LITERAL_RE.exec(access[1] ?? "");
@@ -2866,7 +3295,7 @@ export function checkStructure(files) {
2866
3295
  ),
2867
3296
  );
2868
3297
  }
2869
- // ADR 0088: App.tsx may also export the type of the values it provides on top of the Shell's.
3298
+ // ADR 0214: App.tsx may also export the type of the values it provides on top of the Shell's.
2870
3299
  const o = (
2871
3300
  path === MAIN_FILE ? APP_OTHER_EXPORT_RE : isPage ? PAGE_OTHER_EXPORT_RE : OTHER_EXPORT_RE
2872
3301
  ).exec(source);
@@ -2879,7 +3308,7 @@ export function checkStructure(files) {
2879
3308
  o[0].length,
2880
3309
  code,
2881
3310
  path === MAIN_FILE
2882
- ? `${path} exports only App and \`type Provided\`, the values it provides to its pages (ADR 0088). Shared values go in ${CONSTANTS_FILE}.`
3311
+ ? `${path} exports only App and \`type Provided\`, the values it provides to its pages (ADR 0214). Shared values go in ${CONSTANTS_FILE}.`
2883
3312
  : `${path} exports only its ${kind}. Shared values go in ${CONSTANTS_FILE}; shared markup is a component.`,
2884
3313
  ),
2885
3314
  );
@@ -2888,7 +3317,7 @@ export function checkStructure(files) {
2888
3317
  return out;
2889
3318
  }
2890
3319
 
2891
- // ---- the rule table (docs/adr/0078) ------------------------------------------------------------------------
3320
+ // ---- the rule table (docs/adr/0236) ------------------------------------------------------------------------
2892
3321
  //
2893
3322
  // Every diagnostic's `code` is one of these ids, stable across releases. A warning never fails a Check, Push,
2894
3323
  // Preview or Deploy; it becomes an error only by a platform release that changes its row here.
@@ -2924,7 +3353,7 @@ export const CHECK_RULES = Object.freeze(
2924
3353
  [
2925
3354
  "hook-export",
2926
3355
  "error",
2927
- "a hooks/ file that does not default-export its named hook, or exports more (ADR 0091)",
3356
+ "a hooks/ file that does not default-export its named hook, or exports more (ADR 0209)",
2928
3357
  "export default function use<Name>()",
2929
3358
  ],
2930
3359
  [
@@ -2948,13 +3377,13 @@ export const CHECK_RULES = Object.freeze(
2948
3377
  [
2949
3378
  "page-access",
2950
3379
  "error",
2951
- "a page's access that is not a literal group condition (docs/adr/0098)",
3380
+ "a page's access that is not a literal group condition (docs/adr/0225)",
2952
3381
  'export const access = "group(payroll) OR group(admins)"',
2953
3382
  ],
2954
3383
  [
2955
3384
  "function-options",
2956
3385
  "error",
2957
- "server function options that are not literal access, authority and api (docs/adr/0098, 0119)",
3386
+ "server function options that are not literal access, authority and api (docs/adr/0225, 0232)",
2958
3387
  'serverFunction(input, handler, { access: "group(payroll)", authority: "site", api: true })',
2959
3388
  ],
2960
3389
  [
@@ -2972,7 +3401,7 @@ export const CHECK_RULES = Object.freeze(
2972
3401
  [
2973
3402
  "no-restricted-imports",
2974
3403
  "error",
2975
- "a React import other than useState, useActionState, useTransition, startTransition, useOptimistic and types",
3404
+ "a React import other than useState, useActionState, useTransition, startTransition, useOptimistic, useMemo, useCallback and types",
2976
3405
  "use the @ezship/react equivalent",
2977
3406
  ],
2978
3407
  [
@@ -2990,12 +3419,12 @@ export const CHECK_RULES = Object.freeze(
2990
3419
  ],
2991
3420
  ["schema", "error", "a db/schema.sql problem", "follow `ez help db`"],
2992
3421
  ["schedules", "error", "a schedules.json problem", "follow `ez help jobs`"],
2993
- ["listeners", "error", "a listeners.json problem (docs/adr/0092)", "follow `ez help jobs`"],
2994
- ["page", "error", "a page.json problem (docs/adr/0148)", "follow `ez help files`"],
3422
+ ["listeners", "error", "a listeners.json problem (docs/adr/0231)", "follow `ez help jobs`"],
3423
+ ["page", "error", "a page.json problem (docs/adr/0209)", "follow `ez help files`"],
2995
3424
  [
2996
3425
  "listener-unlisted",
2997
3426
  "warning",
2998
- "a listeners/ file that listeners.json does not name (docs/adr/0092)",
3427
+ "a listeners/ file that listeners.json does not name (docs/adr/0231)",
2999
3428
  "add it to listeners.json, or delete it",
3000
3429
  ],
3001
3430
  [
@@ -3007,7 +3436,7 @@ export const CHECK_RULES = Object.freeze(
3007
3436
  [
3008
3437
  "workflow-shape",
3009
3438
  "error",
3010
- "a global/workflows/<table>.ts whose column, initial, states or actions are not written out as literals (docs/adr/0103)",
3439
+ "a global/workflows/<table>.ts whose column, initial, states or actions are not written out as literals (docs/adr/0227)",
3011
3440
  "write column and initial as strings and states and actions as object literals, each automatic action with auto: true",
3012
3441
  ],
3013
3442
  [
@@ -3051,7 +3480,7 @@ export const CHECK_RULES = Object.freeze(
3051
3480
  [
3052
3481
  "integration-literal",
3053
3482
  "error",
3054
- "context.integration(...) with anything but a string literal name (docs/adr/0092)",
3483
+ "context.integration(...) with anything but a string literal name (docs/adr/0231)",
3055
3484
  'context.integration("<name>"), the name an Admin set with ez integration set',
3056
3485
  ],
3057
3486
  [
@@ -3069,19 +3498,19 @@ export const CHECK_RULES = Object.freeze(
3069
3498
  [
3070
3499
  "disable-comment",
3071
3500
  "warning",
3072
- "an eslint-disable or oxlint-disable comment: Site code has no escape hatch, so it turns nothing off (docs/adr/0121)",
3501
+ "an eslint-disable or oxlint-disable comment: Site code has no escape hatch, so it turns nothing off (docs/adr/0236)",
3073
3502
  "fix the finding it meant to hide, and delete the comment",
3074
3503
  ],
3075
3504
  [
3076
3505
  "@typescript-eslint/switch-exhaustiveness-check",
3077
3506
  "warning",
3078
- "a switch over a union (a CHECK list's values, a workflow's states) that names neither every member nor a default (docs/adr/0154)",
3507
+ "a switch over a union (a CHECK list's values, a workflow's states) that names neither every member nor a default (docs/adr/0236)",
3079
3508
  "add a case for each value the message lists, or a default (an empty column's null need not be named)",
3080
3509
  ],
3081
3510
  [
3082
3511
  "floating-write",
3083
3512
  "warning",
3084
- "a db write or server-function call whose promise nobody awaits (one handed to a component whose prop takes a promise passes, docs/adr/0154)",
3513
+ "a db write or server-function call whose promise nobody awaits (one handed to a component whose prop takes a promise passes, docs/adr/0236)",
3085
3514
  "one click: onClick={() => run(() => db.update(...))}; a form: await it in useActionState(attempt(async () => ...), null)",
3086
3515
  ],
3087
3516
  [
@@ -3102,23 +3531,11 @@ export const CHECK_RULES = Object.freeze(
3102
3531
  "a list key from the .map index",
3103
3532
  "use the row's id as key: key={row.id}",
3104
3533
  ],
3105
- [
3106
- "ne-nullable",
3107
- "warning",
3108
- "{ col: { ne: x } } on a nullable column: it also drops rows where col is NULL (a type error too on a Table named in the code, docs/adr/0154)",
3109
- "{ nin: [x] } keeps the NULL rows, { nin: [x], null: false } drops them; ne only on id and created_at",
3110
- ],
3111
- [
3112
- "reduce-rows",
3113
- "warning",
3114
- "a total or count computed from capped rows (1000 at most): .reduce, a filtered .length, or a loop adding up per row or per group",
3115
- "use useLive.aggregate / useLive.count / db.aggregate",
3116
- ],
3117
3534
  [
3118
3535
  "filter-rows",
3119
3536
  "warning",
3120
3537
  "capped rows (100 by default) searched, filtered or paged in the page by what the user typed or picked",
3121
- "put the condition in the query's where ({ col: { like } }) and paging in limit/offset; show useLive.query's truncated",
3538
+ "put the condition in the query's where ({ col: { contains } }) and paging in limit/offset; show useLive.query's truncated",
3122
3539
  ],
3123
3540
  [
3124
3541
  "in-list-size",
@@ -3126,12 +3543,6 @@ export const CHECK_RULES = Object.freeze(
3126
3543
  "an in filter built from a query whose limit is above 400",
3127
3544
  "split the list into chunks, or filter on a column instead",
3128
3545
  ],
3129
- [
3130
- "fn-op-budget",
3131
- "warning",
3132
- "a write inside a loop that is unbounded or may run more than 250 times (900 if it reads Date.now()) in a server function or job",
3133
- "a call has 5 seconds of database time and 1,000 database operations: use insertMany, updateMany or deleteMany with a limit (ez help functions), bound the loop, or write in chunks from several calls",
3134
- ],
3135
3546
  [
3136
3547
  "redundant-transaction",
3137
3548
  "warning",
@@ -3153,43 +3564,49 @@ export const CHECK_RULES = Object.freeze(
3153
3564
  [
3154
3565
  "schema-real-money",
3155
3566
  "warning",
3156
- "a REAL column named like money (price, amount, total, ...) (docs/adr/0107)",
3567
+ "a REAL column named like money (price, amount, total, ...) (docs/adr/0217)",
3157
3568
  "declare <col> MONEY: whole cents, typed Cents; convert input with toCents()",
3158
3569
  ],
3159
3570
  [
3160
3571
  "table-cast",
3161
3572
  "warning",
3162
- 'a cast in a Table argument (name as "orders") or to Query, Insert, Update, Where or Row (docs/adr/0109)',
3573
+ 'a cast in a Table argument (name as "orders") or to Query, Insert, Update, Where or Row (docs/adr/0222)',
3163
3574
  "a Table named at run time: db.table(name) or useLive.table(name, query); otherwise a literal name and no cast",
3164
3575
  ],
3165
3576
  [
3166
3577
  "query-sentinel",
3167
3578
  "warning",
3168
- 'an empty id cast to match nothing: where: { id: "" as Id<...> } (docs/adr/0109)',
3579
+ 'an empty id cast to match nothing: where: { id: "" as Id<...> } (docs/adr/0222)',
3169
3580
  "skip the query: useLive(table, null), useLive.query(table, null), useLive.count(table, null)",
3170
3581
  ],
3171
3582
  [
3172
3583
  "error-text-match",
3173
3584
  "warning",
3174
- "an error's message tested for words: errorMessage(e).includes(...), /x/.test(e.message) (docs/adr/0109)",
3585
+ "an error's message tested for words: errorMessage(e).includes(...), /x/.test(e.message) (docs/adr/0222)",
3175
3586
  'test the code: e instanceof WriteError && e.code === "unique"',
3176
3587
  ],
3177
3588
  [
3178
3589
  "enum-literal-copy",
3179
3590
  "warning",
3180
- "an array of strings that copies a CHECK list from global/db/schema.sql (docs/adr/0109)",
3591
+ "an array of strings that copies a CHECK list from global/db/schema.sql, in a page, component, hook or constants.ts; server code, which cannot read the descriptor, keeps its own (docs/adr/0222)",
3181
3592
  'read schema.column("<table>", "<col>")?.values, or let RecordForm and RecordList draw the choices',
3182
3593
  ],
3183
3594
  [
3184
3595
  "inline-style",
3185
3596
  "warning",
3186
- "a JSX style={{ ... }} whose every value is a literal (docs/adr/0108)",
3597
+ "a JSX style={{ ... }} whose every value is a literal (docs/adr/0215)",
3187
3598
  "move these to a class in style.css and use className",
3188
3599
  ],
3600
+ [
3601
+ "theme-override",
3602
+ "warning",
3603
+ "a Site's style.css that sets a token of the Theme (global/style.css) or restyles a selector the Theme styles, such as body, input or .row (docs/adr/0210)",
3604
+ "change the Theme in global/style.css, or use a name and a class of the Site's own",
3605
+ ],
3189
3606
  ]).map(([id, severity, summary, fix]) => Object.freeze({ id, severity, summary, fix })),
3190
3607
  );
3191
3608
 
3192
- /** The date before which no warning in `CHECK_RULES` becomes an error (docs/adr/0078). */
3609
+ /** The date before which no warning in `CHECK_RULES` becomes an error (docs/adr/0236). */
3193
3610
  const WARNINGS_UNTIL = "2026-12-01";
3194
3611
 
3195
3612
  /** @type {typeof import("./commands.d.mts").helpRules} */
@@ -3290,7 +3707,7 @@ export const RESERVED_INSTANCE_IDS = new Set([
3290
3707
  "agents",
3291
3708
  "i",
3292
3709
  "s",
3293
- // Names under the managed domain that are not Instances (ADR 0064).
3710
+ // Names under the managed domain that are not Instances (ADR 0245).
3294
3711
  "www",
3295
3712
  "chatgpt",
3296
3713
  // The Developers' admin portal, a Worker beside the Studio (ezship-ops).
@@ -3303,49 +3720,29 @@ export function isValidInstanceId(id) {
3303
3720
  }
3304
3721
 
3305
3722
  /**
3306
- * Site ids are permanent and public. The platform assigns random IDs at creation (ADR 0032);
3307
- * this shape also accepts existing named IDs, whose links remain valid.
3723
+ * Site ids are permanent and public: 12 characters of Crockford's base 32 in lowercase (no i, l, o or u), which
3724
+ * the platform draws at random when it creates the Site (ADR 0201).
3308
3725
  * @type {typeof import("./commands.d.mts").SITE_ID_RE}
3309
3726
  */
3310
- export const SITE_ID_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
3311
- /**
3312
- * Path segments the Worker or studio use themselves; never a Site id.
3313
- * @type {typeof import("./commands.d.mts").RESERVED_SITE_IDS}
3314
- */
3315
- export const RESERVED_SITE_IDS = new Set([
3316
- "app",
3317
- "s",
3318
- "i",
3319
- "api",
3320
- "auth",
3321
- "studio",
3322
- "static",
3323
- "assets",
3324
- "cli",
3325
- "preview",
3326
- "agents",
3327
- "settings",
3328
- "global", // the Global Workspace's target id
3329
- ]);
3330
-
3727
+ export const SITE_ID_RE = /^[0-9a-hjkmnp-tv-z]{12}$/;
3331
3728
  /** @type {typeof import("./commands.d.mts").isValidSiteId} */
3332
3729
  export function isValidSiteId(id) {
3333
- return typeof id === "string" && SITE_ID_RE.test(id) && !RESERVED_SITE_IDS.has(id);
3730
+ return typeof id === "string" && SITE_ID_RE.test(id);
3334
3731
  }
3335
3732
 
3336
3733
  /**
3337
- * An Instance folder on disk holds `global/` and `sites/<folder>/`, one per Site (ADR 0079).
3734
+ * An Instance folder on disk holds `global/` and `sites/<folder>/`, one per Site (ADR 0205).
3338
3735
  * @type {typeof import("./commands.d.mts").SITES_FOLDER}
3339
3736
  */
3340
3737
  export const SITES_FOLDER = "sites";
3341
3738
  /**
3342
- * The folder names an Instance folder keeps for itself; no Site name may slugify to one (ADR 0079).
3739
+ * The folder names an Instance folder keeps for itself; no Site name may slugify to one (ADR 0205).
3343
3740
  * @type {typeof import("./commands.d.mts").RESERVED_FOLDER_NAMES}
3344
3741
  */
3345
3742
  export const RESERVED_FOLDER_NAMES = new Set([GLOBAL_ID, SITES_FOLDER]);
3346
3743
 
3347
3744
  /**
3348
- * A display name as a folder name: lowercase, hyphen-separated, never empty (ADR 0034).
3745
+ * A display name as a folder name: lowercase, hyphen-separated, never empty (ADR 0205).
3349
3746
  * @type {typeof import("./commands.d.mts").siteFolderName}
3350
3747
  */
3351
3748
  export function siteFolderName(name) {
@@ -3366,7 +3763,7 @@ export function siteNameError(name) {
3366
3763
  return null;
3367
3764
  }
3368
3765
 
3369
- // ---- Previews (docs/adr/0013) ---------------------------------------------------------------------------
3766
+ // ---- Previews (docs/adr/0212) ---------------------------------------------------------------------------
3370
3767
 
3371
3768
  /**
3372
3769
  * The path segment under a Site's prefix that serves a Preview: <prefix>/~preview/<id>/.
@@ -3386,13 +3783,13 @@ export const MAX_PREVIEWS_PER_BUILDER = 10;
3386
3783
  */
3387
3784
  export const PREVIEW_IDLE_MS = 7 * 24 * 60 * 60 * 1000;
3388
3785
  /**
3389
- * One-time app links (docs/adr/0059): `ez link` opens the app or a Preview signed in as the caller's own
3786
+ * One-time app links (docs/adr/0203): `ez link` opens the app or a Preview signed in as the caller's own
3390
3787
  * Member identity; the link works once, within this long.
3391
3788
  * @type {typeof import("./commands.d.mts").APP_LINK_TTL_MS}
3392
3789
  */
3393
3790
  export const APP_LINK_TTL_MS = 5 * 60 * 1000;
3394
3791
  /**
3395
- * Support Requests (docs/adr/0080): a subject and a body for the Host's Developers, a few a day per Builder.
3792
+ * Support Requests (docs/adr/0208): a subject and a body for the Host's Developers, a few a day per Builder.
3396
3793
  * @type {typeof import("./commands.d.mts").SUPPORT_SUBJECT_MAX}
3397
3794
  */
3398
3795
  export const SUPPORT_SUBJECT_MAX = 200;
@@ -3401,7 +3798,7 @@ export const SUPPORT_BODY_MAX = 20_000;
3401
3798
  /** @type {typeof import("./commands.d.mts").SUPPORT_REQUESTS_PER_DAY} */
3402
3799
  export const SUPPORT_REQUESTS_PER_DAY = 10;
3403
3800
 
3404
- // ---- Emails (docs/adr/0149) ---------------------------------------------------------------------------
3801
+ // ---- Emails (docs/adr/0234) ---------------------------------------------------------------------------
3405
3802
 
3406
3803
  /**
3407
3804
  * What `email.send` takes and how much the Host sends: Emails per invocation, the subject's and the body's
@@ -3429,7 +3826,7 @@ export const EMAIL_STATUSES = Object.freeze([
3429
3826
  "dropped",
3430
3827
  ]);
3431
3828
 
3432
- // ---- Integrations (docs/adr/0092, 0094) -----------------------------------------------------------------
3829
+ // ---- Integrations (docs/adr/0231) -----------------------------------------------------------------
3433
3830
  //
3434
3831
  // An Instance's named external services, set by Admins, called by server code with a credential it never
3435
3832
  // sees. The names, kinds, credential types and limits are data here, for the CLI, the Pipeline and the Host.
@@ -3459,7 +3856,7 @@ export const INTEGRATION_LIMITS = Object.freeze({
3459
3856
  inFlightPerInstance: 4,
3460
3857
  perSecond: 10,
3461
3858
  burst: 60,
3462
- // ADR 0138: a binding's values, the headers it may add in all, and the shortest secret the Host looks
3859
+ // ADR 0231: a binding's values, the headers it may add in all, and the shortest secret the Host looks
3463
3860
  // for in an answer (and shows a hint of).
3464
3861
  valuesPerBinding: 20,
3465
3862
  addedHeaderBytes: 8192,
@@ -3539,7 +3936,7 @@ export function basicUserError(user) {
3539
3936
  return null;
3540
3937
  }
3541
3938
 
3542
- // ---- OAuth (docs/adr/0140, a draft) --------------------------------------------------------------------
3939
+ // ---- OAuth (docs/adr/0252, a draft) --------------------------------------------------------------------
3543
3940
  //
3544
3941
  // An OAuth credential is stored and listed, and every call on it is refused `grant` ("not connected"),
3545
3942
  // until the draft's flows (connect, the callback, refresh) are built. Presets are provider facts, data here.
@@ -3553,10 +3950,10 @@ export const OAUTH_CLIENT_AUTH = Object.freeze(/** @type {const} */ (["basic", "
3553
3950
  /** What `ez integration` says of an OAuth credential while the draft's flows are not built. */
3554
3951
  /** @type {typeof import("./commands.d.mts").OAUTH_NOT_BUILT} */
3555
3952
  export const OAUTH_NOT_BUILT =
3556
- "OAuth flows are not implemented yet (ADR 0140, a draft): the credential is stored, but nothing can connect it, so every call is refused until they are.";
3953
+ "OAuth flows are not implemented yet (ADR 0231, a draft): the credential is stored, but nothing can connect it, so every call is refused until they are.";
3557
3954
 
3558
3955
  /**
3559
- * Providers whose OAuth facts are certain (docs/adr/0140): the API's origin and its sandbox's, the URLs, the
3956
+ * Providers whose OAuth facts are certain (docs/adr/0231): the API's origin and its sandbox's, the URLs, the
3560
3957
  * default scopes, the client's authentication, and the plain values every request needs.
3561
3958
  * @type {typeof import("./commands.d.mts").OAUTH_PRESETS}
3562
3959
  */
@@ -3643,9 +4040,9 @@ export function oauthCredentialError(c, allowHttp = false) {
3643
4040
  return null;
3644
4041
  }
3645
4042
 
3646
- // ---- invites (docs/adr/0025) ----------------------------------------------------------------------------
4043
+ // ---- invites (docs/adr/0202) ----------------------------------------------------------------------------
3647
4044
  //
3648
- // An invite is a pre-created identity row (docs/adr/0002) that the person claims by signing in. It is claimable
4045
+ // An invite is a pre-created identity row (docs/adr/0202) that the person claims by signing in. It is claimable
3649
4046
  // for INVITE_TTL_MS after the last invite from any Instance; re-adding the person restarts the window.
3650
4047
 
3651
4048
  /** @type {typeof import("./commands.d.mts").INVITE_TTL_MS} */
@@ -3752,7 +4149,7 @@ export const ROUTES = Object.freeze({
3752
4149
  instanceStatus: { method: "GET", path: INSTANCE },
3753
4150
  updateInstance: { method: "PATCH", path: INSTANCE, args: (patch) => body(patch) },
3754
4151
  listAudit: { method: "GET", path: `${INSTANCE}/audit`, args: (filter) => ({ query: filter }) },
3755
- // the App Database is the Instance's (docs/adr/0007): no Site in the path
4152
+ // the App Database is the Instance's (docs/adr/0217): no Site in the path
3756
4153
  dbSchema: { method: "GET", path: `${INSTANCE}/db/schema` },
3757
4154
  dbTables: { method: "GET", path: `${INSTANCE}/db/tables` },
3758
4155
  dbSql: { method: "POST", path: `${INSTANCE}/db/sql`, args: (statement) => body({ statement }) },
@@ -3762,15 +4159,15 @@ export const ROUTES = Object.freeze({
3762
4159
  args: (table, query) => ({ params: { table }, body: query }),
3763
4160
  },
3764
4161
  dbActors: { method: "POST", path: `${INSTANCE}/db/actors`, args: (query) => body(query) },
3765
- // A read-only query as one Member sees the rows (docs/adr/0098), for testing access rules.
4162
+ // A read-only query as one Member sees the rows (docs/adr/0225), for testing access rules.
3766
4163
  dbQueryAs: {
3767
4164
  method: "POST",
3768
4165
  path: `${INSTANCE}/db/query/:table`,
3769
4166
  args: (table, as, query) => ({ params: { table }, body: { as, query } }),
3770
4167
  },
3771
- // the one write to a History (docs/adr/0106); Admins only, and no Site code reaches it
4168
+ // the one write to a History (docs/adr/0218); Admins only, and no Site code reaches it
3772
4169
  dbRedact: { method: "POST", path: `${INSTANCE}/db/redact`, args: (input) => body(input) },
3773
- // App Attachments (docs/adr/0047); the bytes go to the ticket's URL (`.../db/attachments/:id/bytes`), outside this table
4170
+ // App Attachments (docs/adr/0221); the bytes go to the ticket's URL (`.../db/attachments/:id/bytes`), outside this table
3774
4171
  requestAttachment: {
3775
4172
  method: "POST",
3776
4173
  path: `${INSTANCE}/db/attachments`,
@@ -3797,24 +4194,24 @@ export const ROUTES = Object.freeze({
3797
4194
  args: (id, status) => ({ params: { id }, body: { status } }),
3798
4195
  },
3799
4196
  removeUser: { method: "DELETE", path: `${INSTANCE}/users/:id`, args: byId },
3800
- // Member groups on the roster (docs/adr/0098): the whole list at once.
4197
+ // Member groups on the roster (docs/adr/0225): the whole list at once.
3801
4198
  setUserGroups: {
3802
4199
  method: "PUT",
3803
4200
  path: `${INSTANCE}/users/:id/groups`,
3804
4201
  args: (id, groups) => ({ params: { id }, body: { groups } }),
3805
4202
  },
3806
- // Support Requests to the Host's Developers (docs/adr/0080)
4203
+ // Support Requests to the Host's Developers (docs/adr/0208)
3807
4204
  openSupportRequest: { method: "POST", path: `${INSTANCE}/support`, args: (input) => body(input) },
3808
4205
  listSupportRequests: { method: "GET", path: `${INSTANCE}/support` },
3809
4206
  supportRequest: { method: "GET", path: `${INSTANCE}/support/:id`, args: byId },
3810
- // Emails server code sent (docs/adr/0149): every Builder reads them; a Limited Builder only their Sites'.
4207
+ // Emails server code sent (docs/adr/0234): every Builder reads them; a Limited Builder only their Sites'.
3811
4208
  listEmails: {
3812
4209
  method: "GET",
3813
4210
  path: `${INSTANCE}/emails`,
3814
4211
  args: (filter) => ({ query: { ...filter } }),
3815
4212
  },
3816
4213
  emailInfo: { method: "GET", path: `${INSTANCE}/emails/:id`, args: byId },
3817
- // Integrations (docs/adr/0092): Admins set them; every Builder lists them and their calls.
4214
+ // Integrations (docs/adr/0231): Admins set them; every Builder lists them and their calls.
3818
4215
  listIntegrations: { method: "GET", path: `${INSTANCE}/integrations` },
3819
4216
  setIntegration: {
3820
4217
  method: "PUT",
@@ -3826,7 +4223,7 @@ export const ROUTES = Object.freeze({
3826
4223
  path: `${INSTANCE}/integrations/:name/preview`,
3827
4224
  args: (name, input) => ({ params: { name }, body: input }),
3828
4225
  },
3829
- // ADR 0138: one header or parameter the Host adds to a binding's every request.
4226
+ // ADR 0231: one header or parameter the Host adds to a binding's every request.
3830
4227
  setIntegrationValue: {
3831
4228
  method: "PUT",
3832
4229
  path: `${INSTANCE}/integrations/:name/values`,
@@ -3855,7 +4252,7 @@ export const ROUTES = Object.freeze({
3855
4252
  path: `${INSTANCE}/integrations/:name/test`,
3856
4253
  args: (name, input) => ({ params: { name }, body: input }),
3857
4254
  },
3858
- // the Instance's schedules (ADRs 0076, 0136), from the pushed global/schedules.json; ADR 0120: a pause is
4255
+ // the Instance's schedules (ADR 0230), from the pushed global/schedules.json; ADR 0230: a pause is
3859
4256
  // the Host's, on the active schedule, and a resume never catches up
3860
4257
  listSchedules: { method: "GET", path: `${INSTANCE}/schedules` },
3861
4258
  listScheduleRuns: {
@@ -3878,15 +4275,10 @@ export const ROUTES = Object.freeze({
3878
4275
  path: `${INSTANCE}/schedules/:name/resume`,
3879
4276
  args: (name) => ({ params: { name } }),
3880
4277
  },
3881
- // the Instance's assets (docs/adr/0014); the bytes go to the ticket's URL, outside this table
4278
+ // the Instance's assets (docs/adr/0213); the bytes go to the ticket's URL, outside this table
3882
4279
  listAssets: { method: "GET", path: `${INSTANCE}/assets` },
3883
4280
  requestUpload: { method: "POST", path: `${INSTANCE}/assets`, args: (input) => body(input) },
3884
4281
  finalizeUpload: { method: "POST", path: `${INSTANCE}/assets/:id/ready`, args: byId },
3885
- deleteAsset: {
3886
- method: "DELETE",
3887
- path: `${INSTANCE}/assets/:id`,
3888
- args: (id, force) => ({ params: { id }, query: force ? { force: 1 } : {} }),
3889
- },
3890
4282
  // the Site
3891
4283
  remoteStatus: { method: "GET", path: `${SITE}/workspace` },
3892
4284
  updateSettings: { method: "PATCH", path: `${SITE}/workspace`, args: (patch) => body(patch) },
@@ -3895,12 +4287,12 @@ export const ROUTES = Object.freeze({
3895
4287
  pushAll: {
3896
4288
  method: "POST",
3897
4289
  path: `${SITE}/push`,
3898
- // `options`: the message (docs/adr/0093) and a Global push's dryRun, acknowledgeExposure and force
3899
- // (docs/adr/0096, 0098).
4290
+ // `options`: the message (docs/adr/0211) and a Global push's dryRun, acknowledgeExposure and force
4291
+ // (docs/adr/0224, 0225).
3900
4292
  args: (files, prune, deleted = [], options = {}) => body({ files, prune, deleted, ...options }),
3901
4293
  },
3902
4294
  deploy: { method: "POST", path: `${SITE}/deploy` },
3903
- // Listeners (docs/adr/0092): any Builder of the Site; a secret travels once, in a PUT's body.
4295
+ // Listeners (docs/adr/0231): any Builder of the Site; a secret travels once, in a PUT's body.
3904
4296
  listListeners: { method: "GET", path: `${SITE}/listeners` },
3905
4297
  setListenerSecret: {
3906
4298
  method: "PUT",
@@ -3927,7 +4319,7 @@ export const ROUTES = Object.freeze({
3927
4319
  path: `${SITE}/listeners/:name/events/:id/retry`,
3928
4320
  args: (name, id) => ({ params: { name, id } }),
3929
4321
  },
3930
- // API Keys (docs/adr/0119, docs/adr/0151): the Instance's; Admins create and revoke, every Builder lists.
4322
+ // API Keys (docs/adr/0232): the Instance's; Admins create and revoke, every Builder lists.
3931
4323
  listApiKeys: { method: "GET", path: `${INSTANCE}/keys` },
3932
4324
  createApiKey: { method: "POST", path: `${INSTANCE}/keys`, args: (input) => body(input) },
3933
4325
  revokeApiKey: {
@@ -3946,7 +4338,7 @@ export const ROUTES = Object.freeze({
3946
4338
  args: (files, global) => body({ files, ...(global ? { global } : {}) }),
3947
4339
  },
3948
4340
  format: { method: "POST", path: `${SITE}/format`, args: (files) => body({ files }) },
3949
- // Documents (docs/adr/0105): in a Site a queued Render; in the Global Workspace (`files`) an immediate one
4341
+ // Documents (docs/adr/0233): in a Site a queued Render; in the Global Workspace (`files`) an immediate one
3950
4342
  renderDocument: {
3951
4343
  method: "POST",
3952
4344
  path: `${SITE}/renders`,
@@ -3977,7 +4369,7 @@ export const ROUTES = Object.freeze({
3977
4369
  denyBuilder: { method: "DELETE", path: `${SITE}/access/builders/:id`, args: byId },
3978
4370
  allowUser: { method: "POST", path: `${SITE}/access/members`, args: (id) => body({ id }) },
3979
4371
  denyUser: { method: "DELETE", path: `${SITE}/access/members/:id`, args: byId },
3980
- // A Restricted Site's groups (docs/adr/0101): their Members may open it too.
4372
+ // A Restricted Site's groups (docs/adr/0225): their Members may open it too.
3981
4373
  allowGroup: {
3982
4374
  method: "POST",
3983
4375
  path: `${SITE}/access/groups`,
@@ -4090,7 +4482,7 @@ export const AUDIT_KINDS = Object.freeze([
4090
4482
  "site.archive",
4091
4483
  "site.config",
4092
4484
  "site.access",
4093
- "builder.password-setup", // Historical (docs/adr/0025 retired setup links); events remain readable.
4485
+ "builder.password-setup", // Historical (docs/adr/0202 retired setup links); events remain readable.
4094
4486
  "member.password-setup",
4095
4487
  "builder.add",
4096
4488
  "builder.role",
@@ -4100,28 +4492,28 @@ export const AUDIT_KINDS = Object.freeze([
4100
4492
  "member.unblock",
4101
4493
  "member.remove",
4102
4494
  "member.session",
4103
- "member.groups", // a Member's roster groups changed (docs/adr/0098)
4495
+ "member.groups", // a Member's roster groups changed (docs/adr/0225)
4104
4496
  "files.push",
4105
4497
  "deploy",
4106
4498
  "preview.schema",
4107
4499
  "asset.add",
4108
4500
  "asset.remove",
4109
4501
  "db.sql", // a write through `ez db sql`; details keep the capped statement text
4110
- "db.attach", // `ez db attach`: an attachment bound to a row (docs/adr/0047)
4111
- "db.query-as", // `ez db query --as`: a Builder read rows as one Member sees them (docs/adr/0098)
4112
- "schedule.run", // `ez schedule run`: a schedule's job run now (docs/adr/0076)
4113
- "schedule.pause", // `ez schedule pause`: a schedule's due times stopped (docs/adr/0120)
4502
+ "db.attach", // `ez db attach`: an attachment bound to a row (docs/adr/0221)
4503
+ "db.query-as", // `ez db query --as`: a Builder read rows as one Member sees them (docs/adr/0225)
4504
+ "schedule.run", // `ez schedule run`: a schedule's job run now (docs/adr/0230)
4505
+ "schedule.pause", // `ez schedule pause`: a schedule's due times stopped (docs/adr/0230)
4114
4506
  "schedule.resume", // `ez schedule resume`: started again from now
4115
- "integration.set", // an Integration's production binding, Sites or timeout (docs/adr/0092)
4507
+ "integration.set", // an Integration's production binding, Sites or timeout (docs/adr/0231)
4116
4508
  "integration.preview", // an Integration's Preview binding
4117
- "integration.value", // a header or parameter a binding adds (docs/adr/0138); a secret one never in details
4509
+ "integration.value", // a header or parameter a binding adds (docs/adr/0231); a secret one never in details
4118
4510
  "integration.remove",
4119
4511
  "integration.test", // `ez integration test`: one request, its path omitted
4120
- "listener.secret", // a Listener's verification secret set or removed (docs/adr/0092)
4512
+ "listener.secret", // a Listener's verification secret set or removed (docs/adr/0231)
4121
4513
  "listener.retry", // a dead event put back to pending
4122
- "api.key", // an API Key created or revoked (docs/adr/0119); never the key
4123
- "document.render", // `ez document render` or `ez global document render` (docs/adr/0105)
4124
- "db.redact", // `ez db redact`: columns blanked in rows and their History (docs/adr/0106); never values
4514
+ "api.key", // an API Key created or revoked (docs/adr/0232); never the key
4515
+ "document.render", // `ez document render` or `ez global document render` (docs/adr/0233)
4516
+ "db.redact", // `ez db redact`: columns blanked in rows and their History (docs/adr/0218); never values
4125
4517
  ]);
4126
4518
 
4127
4519
  // ---- change tracking -----------------------------------------------------------------------------------
@@ -4170,7 +4562,7 @@ export const countChanges = (c) => c.added.length + c.modified.length + c.delete
4170
4562
  // Tags say what kind of statement a line is: [check] ez check (and push/preview/deploy) refuses it with a rule
4171
4563
  // id, [runtime] the Host refuses or limits it when it runs, [advice] a default to follow that nothing checks.
4172
4564
 
4173
- /** `ez help` and `ez help lifecycle`: what each command reads, changes and shows (docs/adr/0013, 0016, 0021, 0096). */
4565
+ /** `ez help` and `ez help lifecycle`: what each command reads, changes and shows (docs/adr/0212, 0210, 0217, 0224). */
4174
4566
  const LIFECYCLE = `The lifecycle: what each command builds from, changes and shows. There are six states: your Site files
4175
4567
  (this Working Copy), your Global files (global/ beside it), the pushed Site and Global Versions (the Shared
4176
4568
  Files every Builder pulls), the deployed Site (a build Members use), the published schema (global
@@ -4237,6 +4629,11 @@ const SITE_FILES = `${aligned([
4237
4629
  "custom hooks, one per file, `export default function use<Name>()`, no markup",
4238
4630
  "ez help frame",
4239
4631
  ],
4632
+ [
4633
+ `${LIB_DIR}<name>.ts`,
4634
+ "this Site's own helpers: named exports, pure TypeScript, imported as ./lib/<name>",
4635
+ "ez help functions",
4636
+ ],
4240
4637
  [
4241
4638
  `${FUNCTIONS_DIR}<name>.ts`,
4242
4639
  "server functions: default-export serverFunction(inputSchema, handler)",
@@ -4355,7 +4752,7 @@ files. What a React developer reaches for, and what to write here:
4355
4752
  ${aligned([
4356
4753
  [
4357
4754
  "load data, live",
4358
- 'useLive("orders", { where: { status: "open" } }); useLive.count, useLive.aggregate',
4755
+ 'useLive.query("orders", { where: { status: "open" } }) -> { rows, truncated, loading }; useLive.count',
4359
4756
  "data",
4360
4757
  ],
4361
4758
  [
@@ -4383,6 +4780,11 @@ ${aligned([
4383
4780
  "functions/<name>.ts: serverFunction(z.object(...), handler)",
4384
4781
  "functions",
4385
4782
  ],
4783
+ [
4784
+ "a rule nobody may get around",
4785
+ "a function that checks, then writes; WRITE <table> BY functions; a Table rule; a workflow",
4786
+ "recipes, db",
4787
+ ],
4386
4788
  [
4387
4789
  "logic pages and functions share",
4388
4790
  "global/lib/<name>.ts: named exports, the db passed in",
@@ -4401,6 +4803,7 @@ ${aligned([
4401
4803
  ["a viewer's preference across pages", 'useSession("activeCompanyId"), Session State', "frame"],
4402
4804
  ["state a link carries", 'useSearchParam("state"); <Link to="/orders?state=open">', "frame"],
4403
4805
  ["stateful logic components share", "hooks/use<Name>.ts, a custom hook", "frame"],
4806
+ ["helpers only this Site uses", "lib/<name>.ts: named exports, pure TypeScript", "functions"],
4404
4807
  ["routes", "pages/<route>.tsx; <Link to>, useNavigate(), useParams()", "files"],
4405
4808
  [
4406
4809
  "who sees which rows",
@@ -4412,7 +4815,7 @@ ${aligned([
4412
4815
  "useAuth() -> { user, membership, me, groups }; sign-in is the platform's",
4413
4816
  "access",
4414
4817
  ],
4415
- ["styling", "className and style.css; the global theme loads first", "files"],
4818
+ ["styling", "className, the Theme's tokens and classes; style.css adds a Site's own", "files"],
4416
4819
  [
4417
4820
  "cron, webhooks, desktop files, PDFs",
4418
4821
  "jobs/, listeners/, local/, global/documents/",
@@ -4420,12 +4823,13 @@ ${aligned([
4420
4823
  ],
4421
4824
  ])}
4422
4825
  Restrictions, each with its replacement:
4423
- [check] From react only useState, useActionState, useTransition, startTransition, useOptimistic and types:
4424
- no useEffect, useRef, useMemo, useCallback, createContext or useContext (data comes from useLive and
4425
- useCall, the React Compiler memoizes, frame values are useProvided). (no-restricted-imports)
4826
+ [check] From react only useState, useActionState, useTransition, startTransition, useOptimistic, useMemo,
4827
+ useCallback and types: no useEffect, useRef, createContext or useContext (data comes from useLive
4828
+ and useCall, frame values are useProvided; the React Compiler memoizes, so useMemo and
4829
+ useCallback are never needed). (no-restricted-imports)
4426
4830
  [check] No fetch, window, document, timers or storage: db and useLive for data, Integrations for other
4427
- services, useSession for preferences, useInterval and useDebounced for time. confirm(), alert()
4428
- and prompt() are allowed in event handlers. (no-restricted-globals)
4831
+ services, useSession for preferences, useInterval and useDebounced for time. confirm(), alert(),
4832
+ prompt() and print() are allowed in event handlers. (no-restricted-globals)
4429
4833
  [check] No packages but recharts, no URLs, dynamic import() or file extensions in imports; only what
4430
4834
  \`ez help files\` lists. Pages are never imported. (import)
4431
4835
  [check] No classes; constants.ts holds plain values only. (class, constant-shape)
@@ -4441,6 +4845,12 @@ Restrictions, each with its replacement:
4441
4845
  [runtime] Preview data is production data: every Preview write is real.
4442
4846
  [advice] Await every write; key list items by the row's id; use errorMessage(e), never \`e as Error\`;
4443
4847
  call hooks at the top of a component. (ez check warns on each: fix warnings too.)
4848
+ [advice] A rule the request states as never, only or must (steps in order, a hold, a gate before release)
4849
+ is enforced on the server, never by a hidden button or a check in a page, which a second tab or
4850
+ another Site gets around: a server function that reads, checks and writes in its one transaction,
4851
+ with \`WRITE <table> BY functions\` in access.sql so no page writes around it; a Table rule when
4852
+ every write of the Table must pass; a workflow when it is which moves a status may make. Record who
4853
+ did it from the function's user.me, never from a typed name. (ez help recipes: enforced-rule)
4444
4854
  [advice] One Site is one audience and a few pages: when a request needs another audience or grows past a
4445
4855
  few pages, say it belongs in another Site. A request outside this shape is a limit to report to
4446
4856
  the user, not a workaround to find.
@@ -4477,6 +4887,24 @@ for a problem in the code you are writing. Keep replies brief.
4477
4887
 
4478
4888
  ${LIFECYCLE}`;
4479
4889
 
4890
+ /**
4891
+ * The starter Theme's tokens, as `ez help files` names them: read from the Theme itself, so they cannot drift,
4892
+ * in lines of the help's width.
4893
+ */
4894
+ const THEME_TOKENS = [
4895
+ ...(/:root \{([^}]*)\}/.exec(STARTER_GLOBAL_FILES[STYLE_FILE])?.[1] ?? "").matchAll(
4896
+ /^\s*(--[\w-]+):/gm,
4897
+ ),
4898
+ ]
4899
+ .map((m) => m[1])
4900
+ .reduce((lines, name) => {
4901
+ const line = lines.at(-1);
4902
+ if (line && (line + ", " + name).length <= 104) lines[lines.length - 1] = line + ", " + name;
4903
+ else lines.push(name);
4904
+ return lines;
4905
+ }, /** @type {string[]} */ ([]))
4906
+ .join(",\n");
4907
+
4480
4908
  /** `ez help files`: the shapes and what each kind of file may import, from the contract's own messages. */
4481
4909
  const FILES_TOPIC = `Files and imports. The Site:
4482
4910
  ${SITE_FILES}
@@ -4484,12 +4912,15 @@ The Global Workspace:
4484
4912
  ${GLOBAL_FILES}
4485
4913
  [check] What each file may import (the same sentences ez check prints):
4486
4914
  Pages, components, hooks and App.tsx: ${IMPORT_SHAPE}
4487
- From react: useState, useActionState, useTransition, startTransition, useOptimistic and types. A page
4915
+ From react: useState, useActionState, useTransition, startTransition, useOptimistic, useMemo, useCallback
4916
+ and types. A global component is global/<Name> or, by its path, global/components/<Name>. A page
4488
4917
  imports \`import type { Provided } from "../App"\` for App.tsx's values (ez help frame).
4489
4918
  Server functions (functions/): @ezship/react/server (serverFunction, z and types), constants, sibling
4490
- functions, global/constants, global/lib/<name>, global/documents/<Name> and type-only global/db/types.
4491
- Listeners: @ezship/react/server, constants, global/constants, global/lib/<name>, type-only
4919
+ functions, ../lib/<name>, global/constants, global/lib/<name>, global/documents/<Name> and type-only
4920
+ global/db/types.
4921
+ Listeners: @ezship/react/server, constants, ../lib/<name>, global/constants, global/lib/<name>, type-only
4492
4922
  global/db/types and sibling functions (not global/documents); nothing imports a listener.
4923
+ Site lib (lib/): ${SITE_LIB_IMPORT_SHAPE}
4493
4924
  Global jobs (global/jobs/): @ezship/react/server, global/lib/<name>, global/constants and type-only
4494
4925
  global/db/types; nothing imports a job.
4495
4926
  Local functions (local/): @ezship/react/local, node:* built-ins, constants, sibling local functions and
@@ -4506,13 +4937,22 @@ Routes: the page file name is the route. index.tsx is /, orders.tsx is /orders,
4506
4937
  /orders/:id (useParams().id), orders.new.tsx is /orders/new. <Link to="/orders/42">, <Link to="/orders"
4507
4938
  site="kitchen"> (another Site of the Instance), useNavigate()(path), useSites() -> [{ id, name, url, current }].
4508
4939
  A Link to the open route has aria-current="page", to its section aria-current="true": style a[aria-current].
4509
- Styling: className and the Site's style.css; the global theme's classes (btn, btn primary, panel, field,
4510
- notice danger, badge, table.data, stack, row, muted, ...) come first. [check] CSS url(), @import and fonts
4511
- only through Assets: asset("logo") is the URL of an image an Admin uploaded with \`ez asset add\` (\`ez asset
4512
- ls\`). [advice] Move a style={{ ... }} of literals into a class (inline-style warns).`;
4513
-
4514
- /**
4515
- * The code blocks of the help topics, as data (docs/adr/0153): a topic prints `code`, and the Pipeline's
4940
+ Styling: className and the Site's style.css, which loads after the Theme (global/style.css). The Theme owns
4941
+ the look of every Site, with its tokens:
4942
+ ${THEME_TOKENS}
4943
+ (read global/style.css for this Instance's) and its classes (btn, btn primary, panel, field, notice danger,
4944
+ badge, table.data, stack, row, muted, ...), which the starter components draw with. [advice] A Site's style.css
4945
+ adds layout and classes of its own, and takes every colour, radius and shadow from a token (background:
4946
+ var(--surface); color: var(--text); border: 1px solid var(--line)): a literal colour does not follow the
4947
+ Theme, and a dark one under the Theme's text cannot be read. Never set a Theme token or restyle what the
4948
+ Theme styles (body, input, .row, .muted) from a Site (theme-override warns). A new look (a dark theme,
4949
+ another brand colour) is a change to the tokens in global/style.css, for every Site at once, when the
4950
+ request is for one. [check] CSS url(), @import and fonts only through Assets: asset("logo") is the URL of
4951
+ an image an Admin uploaded with \`ez asset add\` (\`ez asset ls\`). [advice] Move a style={{ ... }} of
4952
+ literals into a class (inline-style warns).`;
4953
+
4954
+ /**
4955
+ * The code blocks of the help topics, as data (docs/adr/0236): a topic prints `code`, and the Pipeline's
4516
4956
  * `help.test.ts` checks `before + code + after` as the file `path`, with no warnings, against the starter
4517
4957
  * Global Workspace and `HELP_SNIPPET_SCHEMA`. Change a block only to code that checks clean.
4518
4958
  * @type {readonly import("./commands.d.mts").HelpSnippet[]}
@@ -4544,10 +4984,10 @@ export default function Chart() {
4544
4984
  before: `import { useLive } from "@ezship/react";
4545
4985
 
4546
4986
  /** Analyses of received samples, with what each references. */
4547
- export default function Analyses({ like }: { like: string }) {
4987
+ export default function Analyses({ search }: { search: string }) {
4548
4988
  `,
4549
4989
  code: `const { rows } = useLive.query("analysis", {
4550
- where: { "sample_id.status": "received", or: [{ code: { like } }, { ref: { like } }] }, // paths filter before paging
4990
+ where: { "sample_id.status": "received", or: [{ code: { contains: search } }, { ref: { contains: search } }] }, // paths filter before paging
4551
4991
  include: { sample_id: ["code"], "sample_id.client_id": ["name"], analyst: ["name"], method_instrument: { instrument_id: ["title"] } },
4552
4992
  order: ["sort_key nulls last"],
4553
4993
  });
@@ -4633,9 +5073,9 @@ export const defaults: Saved & SignedIn = { activeCompanyId: null, favorites: []
4633
5073
  `,
4634
5074
  code: `import { useLive } from "@ezship/react";
4635
5075
  export default function useOpenOrders(customerId: string) {
4636
- const orders = useLive("orders", { where: { customer_id: customerId, status: "open" } });
5076
+ const orders = useLive.query("orders", { where: { customer_id: customerId, status: "open" } });
4637
5077
  const total = useLive.aggregate("orders", { where: { customer_id: customerId, status: "open" }, sum: ["amount"] });
4638
- return { orders, total: total.rows[0]?.sum.amount ?? 0 };
5078
+ return { orders: orders.rows, loading: orders.loading, total: total.rows[0]?.sum.amount ?? 0 };
4639
5079
  }
4640
5080
  `,
4641
5081
  },
@@ -4660,7 +5100,7 @@ export default serverFunction(z.object({ title: z.string().min(1) }), async ({ d
4660
5100
  /** Marks one page of items synced and says whether more remain. */
4661
5101
  export default serverFunction(z.object({}), async ({ db }) => {
4662
5102
  `,
4663
- code: `const { more } = await db.updateMany("items", { where: { synced: 0 }, limit: 100 }, { synced: 1 });
5103
+ code: `const { more } = await db.updateMany("items", { where: { synced: { ne: true } }, limit: 100 }, { synced: true });
4664
5104
  return { more };
4665
5105
  `,
4666
5106
  after: `});
@@ -4672,15 +5112,17 @@ return { more };
4672
5112
  path: "functions/syncSome.ts",
4673
5113
  before: `import { serverFunction, z } from "@ezship/react/server";
4674
5114
 
4675
- /** Marks items synced one by one for as long as the call has time. */
4676
- export default serverFunction(z.object({}), async ({ db }) => {
5115
+ /** Marks items synced one by one for as long as the call has time, and says whether more remain. */
5116
+ export default serverFunction(z.object({}), async ({ db, timeLeft }) => {
4677
5117
  `,
4678
- code: `const from = Date.now(); // in code that calls an integration, take it just before the first write
4679
- const rows = await db.list("items", { where: { synced: 0 }, limit: 900 });
5118
+ code: `const { rows, truncated } = await db.query("items", { where: { synced: { ne: true } }, limit: 500 });
5119
+ let done = 0;
4680
5120
  for (const row of rows) {
4681
- if (Date.now() - from > 4000) break;
4682
- await db.update("items", row.id, { synced: 1 });
5121
+ if (timeLeft() === 0) break;
5122
+ await db.update("items", row.id, { synced: true });
5123
+ done++;
4683
5124
  }
5125
+ return { more: truncated || done < rows.length };
4684
5126
  `,
4685
5127
  after: `});
4686
5128
  `,
@@ -4709,7 +5151,7 @@ CREATE TABLE orders (
4709
5151
  status TEXT CHECK (status IN ('open', 'shipped', 'paid')),
4710
5152
  amount MONEY
4711
5153
  );
4712
- CREATE TABLE items (title TEXT, hours REAL, synced INTEGER);
5154
+ CREATE TABLE items (title TEXT, hours REAL, synced BOOLEAN);
4713
5155
  CREATE TABLE accounting_periods (ends_on DATE, closed INTEGER);
4714
5156
  CREATE TABLE client (name TEXT);
4715
5157
  CREATE TABLE sample (
@@ -4747,14 +5189,18 @@ function snippet(name) {
4747
5189
  const DATA_TOPIC = `Data: reading and writing the App Database from pages, components and hooks (all from @ezship/react).
4748
5190
  Tables belong to the Instance: every Site shares them. Declare them in global/db/schema.sql (\`ez help db\`);
4749
5191
  types come from \`import type { Order } from "global/db/types"\`, and rows are Row<"orders">.
4750
- useLive("orders", { where: { status: "open" }, order: ["-created_at"] }) -> Row<"orders">[], re-renders when the table changes
4751
- useLive("orders", null) -> [] and no subscription: a query waiting on another's answer (never { id: "" })
4752
- useLive.query(table, query) / db.query(table, query) -> { rows, truncated } (live queries add loading)
5192
+ One read shape (docs/adr/0219): a read answers { rows, truncated }, live in a component and one-shot in a handler.
5193
+ const { rows, truncated, loading } = useLive.query("orders", { where: { status: "open" }, order: ["-created_at"] })
5194
+ -> rows: Row<"orders">[], re-rendered when the Table changes; truncated: more rows match than limit took
5195
+ const { rows, truncated } = await db.query("orders", query) -> the same read once, in an event handler or server code
5196
+ useLive.query("orders", null) -> no rows and no subscription: a query waiting on another's answer (never { id: "" })
5197
+ useLive("orders", query) and db.list("orders", query) are shorthand for the rows alone, for a read that cannot
5198
+ reach its limit (one parent's children, a short lookup Table); they cannot say that rows were left out
4753
5199
  useLive.count("orders", { where: { status: "shipped" } }) -> the complete count, undefined while loading
4754
5200
  useLive.aggregate("orders", { group: ["status"], sum: ["amount"] }) -> { rows: [{ group, count, sum }], truncated, loading, version }
4755
- Charts are recharts (ADR 0114), fed an aggregate's rows (stats = the useLive.aggregate above):
5201
+ Charts are recharts (ADR 0209), fed an aggregate's rows (stats = the useLive.aggregate above):
4756
5202
  ${snippet("chart")}
4757
- db.list(table, query) / db.get(table, id) / db.count(table, { where }) / db.aggregate(table, query) -> one-shot, in event handlers
5203
+ db.get(table, id) / db.count(table, { where }) / db.aggregate(table, query) -> one-shot, in event handlers
4758
5204
  db.insert("orders", { customer, status: "new" }); db.update("orders", id, { status: "ready" }); db.delete("orders", id)
4759
5205
  db.update("orders", id, { status: "paid" }, { why: "Invoice paid by card" }) -> the reason lands in that write's History row
4760
5206
  db.settings("company_settings") -> a SINGLETON Table's row or null
@@ -4765,24 +5211,30 @@ ${snippet("chart")}
4765
5211
  today(), toDate(2026, 3, 1), toDate(date), toEpoch("2026-03-01"), now() -> DATE (DateString) and TIMESTAMP (EpochMs) values
4766
5212
  toCents("1,234.50"), toCents(12.5), fromCents(cents) -> MONEY values (whole cents; null when unreadable)
4767
5213
  where: { col: value } is equality ({ col: null } is IS NULL); { col: { gte: 2 } } uses eq ne lt lte gt gte in
4768
- nin like null has; or: [{ ... }, { ... }]; and: [{ or: [...] }, { or: [...] }] for several ors. { in: [] }
4769
- matches nothing. [check] ne is typed only for a column no row leaves empty (id, created_at): anywhere else it
4770
- would also drop the NULL rows, so say which you mean: { nin: [x] } keeps them, { nin: [x], null: false }
4771
- drops them (types, ne-nullable).
4772
- [runtime] like matches the whole value: % is any run of characters and _ is one, and it ignores case for ASCII
4773
- letters only (A and a match; É and é do not).
4774
- [runtime] Row queries default to 100 rows and cap at 1000. [check, warning] Never compute a total or count
4775
- from rows, by reduce or by a loop (reduce-rows): use count and aggregate, which are complete. Never search,
4776
- filter or page loaded rows by what the user typed or picked (filter-rows): put it in where and limit/offset,
4777
- and show useLive.query's truncated. Aggregate filters apply before grouping; limit/offset page the groups,
4778
- which can be truncated too. Ungrouped empty input counts zero.
4779
- Relations (ADR 0102): [advice] never join in the browser or build id maps; one query follows REFERENCES.
5214
+ nin contains startsWith endsWith like null has; or: [{ ... }, { ... }]; and: [{ or: [...] }, { or: [...] }] for
5215
+ several ors. { in: [] } matches nothing.
5216
+ [runtime] A filter means what the same test on a row would in TypeScript (docs/adr/0219): { col: { ne: x } } is
5217
+ row.col !== x and { col: { nin: [x, y] } } is "neither", so both keep the rows where col is empty; add
5218
+ null: false to drop those ({ ne: x, null: false }). { ne: null } is "has a value". The ordering operators
5219
+ (lt lte gt gte) and the text ones never match an empty column. A path through a reference tests the referenced
5220
+ row: { "sample_id.code": { ne: x } } leaves out the rows whose sample_id is empty, ne and nin included; or it
5221
+ with { sample_id: null } to keep them.
5222
+ [runtime] Text search is { name: { contains: text } }, startsWith or endsWith: text is taken as written (a % or _
5223
+ in it is that character), on a TEXT column, ignoring case for ASCII letters only (A and a match; É and é do
5224
+ not). like is the same match against a pattern over the whole value, % any run of characters and _ one.
5225
+ [runtime] Row queries default to 100 rows and cap at 1000, and a Preview says when a plain useLive read stopped
5226
+ at its limit. [advice] A total or count comes from count and aggregate, which are complete, never from adding
5227
+ up rows that may have stopped. [check, warning] Never search, filter or page loaded rows by what the user typed
5228
+ or picked (filter-rows): put it in where ({ col: { contains } }) and limit/offset, and show truncated. Aggregate
5229
+ filters apply before grouping; limit/offset page the groups, which can be truncated too. Ungrouped empty
5230
+ input counts zero.
5231
+ Relations (ADR 0219): [advice] never join in the browser or build id maps; one query follows REFERENCES.
4780
5232
  ${snippet("relations")}
4781
5233
  -> row.sample?.code, row.sample?.client?.name, row.analyst_row?.name (an actor), row.method_instrument[i].instrument?.title
4782
5234
  A <name>_id include lands on row.<name>, <name>_ids (an id list) on row.<name> as an array, any other column c
4783
5235
  on row.c_row; a child Table on row.<child> (up to 100, oldest first; truncatedChildren says more exist; its
4784
5236
  column needs an index). Unreadable rows are null or left out. { ids: { has: id } } tests an id list.
4785
- db.list, query and aggregate take the same where and include, in pages, functions and rules.
5237
+ db.query, db.list and aggregate take the same where and include, in pages, functions and rules.
4786
5238
  History: every Table has a read-only \`<table>_history\` the platform writes on every change, with the actor
4787
5239
  and the write's why. [advice] Never build a log or audit table; an activity feed reads the History
4788
5240
  (\`ez help db\`). The actors view is read-only: match History's by to actors.id, show the current name, and
@@ -4793,7 +5245,7 @@ Refused writes reject with a WriteError: \`catch (e) { if (e instanceof WriteErr
4793
5245
 
4794
5246
  /** `ez help forms`: writes from the UI, actions and the schema-driven record components. */
4795
5247
  const FORMS_TOPIC = `Forms and actions: how the UI writes, and the schema's record components.
4796
- Records from the schema (ADR 0109): reach for these before writing a list, a form, a picker or a reference
5248
+ Records from the schema (ADR 0222): reach for these before writing a list, a form, a picker or a reference
4797
5249
  label by hand. They draw labels, inputs, choices and refusals from global/db/schema.sql (LABEL, DISPLAY,
4798
5250
  CHECK, REFERENCES; \`ez help db\`), so [advice] never re-declare those in Site code.
4799
5251
  <RecordList table="dealers" columns={["customer_code", "name", "credit_hold"]} search={["name", "customer_code"]}
@@ -4807,6 +5259,18 @@ CHECK, REFERENCES; \`ez help db\`), so [advice] never re-declare those in Site c
4807
5259
  <MemberPicker value={m} onChange={setM} />, <CellValue table="dealers" column="credit_hold" value={v} />
4808
5260
  schema.table("dealers") -> { label, plural, display, columns, referencedBy, ... }; schema.label("dealers", row)
4809
5261
  schema.column("orders", "status")?.values -> a CHECK list's choices (never copy them: enum-literal-copy warns)
5262
+ A form the schema cannot draw (it calls a server function, or its fields are not one Table's columns) is the
5263
+ starter's Form with its typed inputs, which hold the label, the hint, the error and the pending state:
5264
+ <Form submit="Log visit" columns={2} onCancel={onClose} action={async () => { await logVisit(input); onClose(); }}>
5265
+ <TextInput label="Name" value={name} onChange={setName} required /> -> string
5266
+ <NumberInput label="Minutes" value={minutes} onChange={setMinutes} /> -> number | null
5267
+ <DateInput label="Date" value={on} onChange={setOn} /> -> DateString | null
5268
+ <SelectInput label="Kind" value={kind} onChange={setKind} options={kinds} />, <TextArea ... />, <Checkbox ... />
5269
+ </Form>
5270
+ [advice] Reach for these before a raw <input>, <select>, <textarea> or <form>; what the action throws shows
5271
+ above the fields (ez help recipes: function-form). Layout is the starter's too: <Stats> around Stat tiles,
5272
+ <Toolbar aside={...}> for the controls above a list, <Board> of <BoardColumn> of <Card> for columns of cards
5273
+ (recipes: board), so a page rarely needs a class of its own. The starter Button takes action or onClick.
4810
5274
  A one-click write (delete, toggle) is onClick={() => run(() => db.delete("orders", id))}: run() awaits it and
4811
5275
  shows the standard failure notice.
4812
5276
  A write with fields or a pending state (a modal's Save, a form) is an action, which replaces the saving flag,
@@ -4819,14 +5283,16 @@ Dispatch the action from onClick={() => startTransition(save)} (both from react)
4819
5283
  id="hours" action={save} noValidate> around the fields and a Save button with form="hours" (it may sit in a
4820
5284
  footer outside the form). A form submits on Enter, but every <button> inside it without type="button" submits
4821
5285
  it too, a child component's (a picker's) included: use the form only when its buttons are typed. noValidate
4822
- leaves validation to the action. [check, warning] Never onClick={save}: React runs it as an action only from
5286
+ leaves validation to the action. React resets a form after its action, which shows a controlled <select> or
5287
+ checkbox at its first value while its state keeps the chosen one: with those inside, submit with
5288
+ onSubmit={(e) => { e.preventDefault(); startTransition(save); }}, as the starter Form does. [check, warning] Never onClick={save}: React runs it as an action only from
4823
5289
  a form, formAction or a transition (form-action). useFormStatus() (from @ezship/react) gives pending to a
4824
5290
  child component inside the form; useTransition gives a pending flag to any async work; useOptimistic shows a
4825
5291
  value before its write lands. An action that throws outside attempt() shows its error in place of the page.
4826
5292
  There is no Modal in the Framework: a dialog is your own component (\`ez help recipes\`, modal-save).
4827
5293
  errorMessage(e) is the message of anything a catch caught. [check, warning] Never cast it (no-cast).`;
4828
5294
 
4829
- /** `ez help frame`: provided values, Session State, query parameters and custom hooks (ADRs 0088, 0091). */
5295
+ /** `ez help frame`: provided values, Session State, query parameters and custom hooks (ADRs 0214 and 0209). */
4830
5296
  const FRAME_TOPIC = `The frame: provided values, Session State, query parameters, custom hooks, the Shell and the viewer.
4831
5297
  Pick by what the value is:
4832
5298
  data the frame works out once (who the viewer is in the app's terms) -> provided values: useProvided()
@@ -4857,7 +5323,7 @@ access by it; a function given activeCompanyId still checks in the App Database
4857
5323
  that company.
4858
5324
  useSearchParam("state") -> that query parameter of the current route, string | null (re-renders when it changes)
4859
5325
  <Link site="dispatch" to="/orders?state=needs_dispatch">; useNavigate()("/orders?driver=" + encodeURIComponent(id))
4860
- Custom hooks (ADR 0091): when a second page or component needs the same live query, Session State or derived
5326
+ Custom hooks (ADR 0209): when a second page or component needs the same live query, Session State or derived
4861
5327
  values, move them into \`hooks/use<Name>.ts\` (or \`global/hooks/use<Name>.ts\` when several Sites share it,
4862
5328
  imported as "global/hooks/use<Name>") rather than copying them. A hook has a component's imports and rules,
4863
5329
  calls hooks at its top level and returns values, never markup:
@@ -4872,7 +5338,7 @@ The viewer: sign-in and membership are the platform's. useAuth() -> { user: { id
4872
5338
  membership: "active" | "blocked" | null, me (the viewer as a MEMBER column holds them), groups, loading };
4873
5339
  signIn() and signOut() are their own imports, not fields of useAuth().`;
4874
5340
 
4875
- /** `ez help functions`: server functions, useCall and Global lib modules (ADRs 0041, 0077). */
5341
+ /** `ez help functions`: server functions, useCall and Global lib modules (ADRs 0228 and 0210). */
4876
5342
  const FUNCTIONS_TOPIC = `Server functions, useCall and shared logic.
4877
5343
  Server functions belong to this Site's Version and deploy with its UI. In functions/save.ts:
4878
5344
  ${snippet("function")}
@@ -4882,8 +5348,8 @@ one when the page opens. useCall takes any async function of its input, so a rep
4882
5348
  limits can load from the page: useCall(({ companyId }) => computeAging(db, companyId), { companyId }), with
4883
5349
  computeAging a global/lib function given the page's db; its db calls are separate requests under the same
4884
5350
  access rules, so prefer aggregates to loops. Neither form is live: refresh() reloads it.
4885
- The handler's context: { db, user, session, documents, integration, members } (ez help integrations, access,
4886
- documents). The db has the caller's access rules and list/query/aggregate/count/get/insert/update/delete and
5351
+ The handler's context: { db, user, session, timeLeft, documents, integration, members } (ez help integrations,
5352
+ access, documents). The db has the caller's access rules and list/query/aggregate/count/get/insert/update/delete and
4887
5353
  insertMany/updateMany/deleteMany (below), typed; user is the validated caller.
4888
5354
  [runtime] Each call is one transaction: all writes and History commit together or all roll back, so never wrap
4889
5355
  a handler's body in db.transaction (redundant-transaction warns); one inside a try still fails the call when
@@ -4904,7 +5370,7 @@ past either, the whole call rolls back ("Function database deadline exceeded").
4904
5370
  counts from its first write instead (ez help integrations). So does a call the Host has not yet seen write, so
4905
5371
  a function can pass once and fail the next time: plan for the first operation. A write takes from about 1 ms on
4906
5372
  an idle Host to 15 ms or more, by its Table and the Host's load, so the 1,000 operations may not fit: plan on 250
4907
- writes per call. (fn-op-budget warns on a write loop that is unbounded or may run more than 250 times.) Other
5373
+ writes per call, and write many rows with insertMany, updateMany or deleteMany (below), one operation each. Other
4908
5374
  writes wait while a call holds the database, so keep what people wait on short.
4909
5375
  [runtime] On a Host that several Instances share, an Instance's calls share 1 second of execution and 250 ms of
4910
5376
  database time a second, with bursts of 60 s and 20 s; past either, a call is refused with 429 and Retry-After. A
@@ -4917,25 +5383,35 @@ others. Each is one database operation and means exactly that many single writes
4917
5383
  rules, workflows (the status column is refused as in an update), unique keys and a History row each. A refusal
4918
5384
  rolls the call back, so none of its rows stand: that includes a row where matches that the caller may read but not
4919
5385
  write (403, naming the row), so narrow where to rows it may write. The 256-KB limit holds for what you pass.
4920
- [advice] Move bulk work in pages, one per call, and let the next call continue while more is true:
5386
+ [runtime] Work too big for one call is done in pieces (docs/adr/0228). context.timeLeft() is the milliseconds the
5387
+ call may still work before it should return: what is left of its deadlines, whichever is nearer, less room for
5388
+ the last write and the commit. It is the Host's count, so the code needs none of the numbers above: loop while
5389
+ it is above 0, then answer { more: true } and let the next call pick up the rest. What a call wrote commits
5390
+ when its handler returns.
5391
+ ${snippet("timed-loop")}
5392
+ The 1,000 operations still hold, so read a bounded batch per call as above. Who calls again:
5393
+ a page await whileMore(syncSome, {}) (from @ezship/react) calls the function until its answer has no
5394
+ more: true, each call its own transaction, and resolves with the last answer (100 calls at most);
5395
+ a call the Host refused with Retry-After (the caller's rate, a busy Host) is made again after it
5396
+ a job a job that answers { more: true } is called again at once in the same run, up to 50 calls or
5397
+ 5 minutes; what is left waits for the schedule's next run (ez help jobs)
5398
+ an API Key the caller repeats the request while the answer says more
5399
+ [advice] A fixed patch over many rows is one operation: page it with updateMany's limit and answer its more:
4921
5400
  ${snippet("many-rows")}
4922
5401
  Page by a condition the write changes: a patch that leaves where true matches the same rows again. The database
4923
- deadline still holds for the whole operation, and past it the call rolls back: 1,000 rows take about half a second
4924
- on an idle Host, or about 2.5 seconds on a Table with rules, and longer on a busy one, so on a Table with rules
4925
- choose a limit well inside 1,000.
4926
- [advice] To adapt to a busy Host, write row by row and stop by time with Date.now(): it is the Host's clock and
4927
- keeps moving while a call waits. Stop at about 4 seconds, which leaves room for the last write and the commit, and
4928
- stay under the 1,000 operations too, since a fast Host reaches them first (fn-op-budget allows up to 900 items in a
4929
- loop that reads Date.now()):
4930
- ${snippet("timed-loop")}
4931
- What it wrote commits when the handler returns; the next call picks up the rest.
5402
+ deadline holds for the whole operation, so on a Table with rules choose a limit well inside 1,000.
4932
5403
  [check] Each function file is one default serverFunction(...) call; keep private helpers inside that file, or in
4933
- a global/lib module once a second file needs them. Options are literals: serverFunction(input, handler,
5404
+ a lib module once a second file needs them (lib/<name>.ts for this Site, global/lib for several; below). Options are literals: serverFunction(input, handler,
4934
5405
  { access: "group(payroll)", authority: "site" }) (ez help access); { api: true } also lets an API Key call it
4935
5406
  (ez help api).
4936
- Test with \`ez function call save '{"title":"Test"}' [--preview <name>]\`; its writes are real (ask first).
4937
- Global lib modules (ADR 0077) hold the logic several Sites or files share: guards, calculations, formatting,
4938
- paged reads. Pages, components, hooks, App.tsx, the Shell, server functions, jobs, listeners, Table rules and
5407
+ Test with \`ez function call save '{"title":"Test"}' [--preview <name>]\`; its writes are real (ask first). It
5408
+ runs as you, under your access rules, and --preview names a Preview of yours.
5409
+ Lib modules hold logic that is not a component, a hook or a function: guards, calculations, parsing, paged
5410
+ reads. lib/<name>.ts is this Site's own (docs/adr/0209): its pages, components, hooks, App.tsx, server functions
5411
+ and listeners import it by path (\`import { priceOf } from "../lib/pricing"\`, "./lib/pricing" from App.tsx), it
5412
+ deploys with the Site, and it may also import the Site's constants. Start there; move a module to global/lib
5413
+ when a second Site needs it.
5414
+ Global lib modules (ADR 0210) hold the logic several Sites share. Pages, components, hooks, App.tsx, the Shell, server functions, jobs, listeners, Table rules and
4939
5415
  workflows import them by name (\`import { periodGuard } from "global/lib/accounting"\`).
4940
5416
  [check] A lib module has named exports only and imports only other lib modules (\`./names\` or
4941
5417
  \`global/lib/names\`) and \`import type\` from \`@ezship/react/server\` and \`global/db/types\`: pure TypeScript with
@@ -4948,7 +5424,7 @@ function, in its transaction. [advice] Move code to lib when a second file needs
4948
5424
  \`ez global check\` checks lib against every Site; a Site's \`ez check\` and \`ez preview\` use the lib in your
4949
5425
  Global Working Copy, unpushed edits included; \`ez deploy\` uses the pushed lib (ez help lifecycle).`;
4950
5426
 
4951
- /** `ez help integrations` (ADRs 0092, 0094). */
5427
+ /** `ez help integrations` (ADR 0231). */
4952
5428
  const INTEGRATIONS_TOPIC = `Integrations let server code (a function, job, listener) reach another service without seeing its
4953
5429
  credentials. [runtime] Pages and local functions have no integrations, and there is no fetch anywhere.
4954
5430
  An Admin sets one in a terminal (\`ez integration set stripe --origin https://api.stripe.com --header
@@ -4973,7 +5449,8 @@ can read the same stock and both write; wrap a read-check-write in db.transactio
4973
5449
  takes the writer at once (no integration call inside or after it). A rollback never undoes a request: pass
4974
5450
  the service an idempotency key where it takes one, and remember a timed-out POST may have happened.
4975
5451
  [runtime] Per call: 5 requests, each within the integration's timeout (default 10 s, at most 30), 60 s in all,
4976
- 256 KB each way, no redirects followed.
5452
+ 256 KB each way, no redirects followed. Per Instance: 4 requests in flight and 10 a second (bursts of 60).
5453
+ Past any limit a request is refused, never queued.
4977
5454
  [runtime] While a service answers, the call's 10-second deadline pauses and it holds no database, so neither its
4978
5455
  requests nor its reads before the first write count toward the 5-second database deadline (ez help functions).
4979
5456
  That deadline starts at the first write or db.transaction: the writes and whatever follows them must fit in it.
@@ -4987,10 +5464,11 @@ are not built yet: every call on one is refused (grant), and \`context.integrati
4987
5464
  [advice] Put a typed wrapper for a service in global/lib (it imports the type IntegrationClient from
4988
5465
  @ezship/react/server and takes the client as an argument, like the database); defaults code may override
4989
5466
  belong there, not on the binding.
4990
- \`ez integration test <name> <path>\` makes one request; \`ez integration calls <name>\` shows recent calls and
5467
+ \`ez integration test <name> <path>\` makes one request (Builders GET and HEAD, Admins any method);
5468
+ \`ez integration calls <name>\` shows recent calls and
4991
5469
  their refusals. A deploy warns when the code names an integration the Instance has not set.`;
4992
5470
 
4993
- /** `ez help jobs`: scheduled jobs and listeners (ADRs 0076, 0092, 0136). */
5471
+ /** `ez help jobs`: scheduled jobs and listeners (ADRs 0230 and 0231). */
4994
5472
  const JOBS_TOPIC = `Scheduled jobs and listeners: server code nothing in the browser calls.
4995
5473
  Scheduled jobs belong to the Instance, not a Site: they live in the Global Workspace and run from its pushed
4996
5474
  schedules.json. In global/jobs/closeDay.ts (\`ez global put jobs/closeDay.ts\`):
@@ -4999,21 +5477,29 @@ schedules.json. In global/jobs/closeDay.ts (\`ez global put jobs/closeDay.ts\`):
4999
5477
  // run.due is the scheduled time (ISO, UTC): use it, not the clock, so a run is idempotent per due time
5000
5478
  });
5001
5479
  and in global/schedules.json: [{ "name": "nightly", "cron": "0 2 * * *", "job": "closeDay", "input": { "days": 1 } }]
5002
- [check] Cron is five UTC fields (minute hour day-of-month month day-of-week); schedules.json is checked
5003
- (schedules), and a Site may hold neither it nor jobs/. A job has a server function's db and limits with Site
5004
- authority (every row but BY none Tables, and context.members); History records it as schedule:<name>.
5480
+ [check] Cron is five UTC fields (minute hour day-of-month month day-of-week; jan-dec and sun-sat names,
5481
+ no @daily or seconds); schedules.json is checked (schedules): at most 20 entries, each input at most 16 KB.
5482
+ A Site may hold neither it nor jobs/. The job's schema checks the input on every run, and a mismatch fails
5483
+ that run. run is { schedule, due, trigger: "schedule" | "manual" }. A job has a server function's db and
5484
+ limits with Site authority (every row but BY none Tables, and context.members); History records it as
5485
+ schedule:<name>.
5005
5486
  Nothing imports a job and no browser can call one; it imports what \`ez help files\` lists for Global jobs, so
5006
5487
  logic it shares with a Site goes in global/lib and its constants in global/constants.
5007
5488
  [runtime] \`ez global push\` activates the schedules and the jobs at once ("Takes effect now"); only Admins
5008
5489
  change schedules.json. Previews never run them. A job sees the Tables and columns a Preview or Deploy has
5009
5490
  created: push alone creates none. Each due time runs at most once; after the Host was down, only the latest
5010
5491
  missed time runs. One run has a function's limits, the 5-second database deadline included (ez help functions),
5011
- and a run past one rolls back whole and is not retried: a long job is several short runs, each writing a bounded
5012
- batch the next continues from, with updateMany's limit and more (ez help functions) or a Date.now() bound; take
5013
- what it stores or keys on from run.due.
5492
+ and a call past one rolls back whole. A run refused because the Host is busy (429, 503) is tried again
5493
+ while it is the latest due time; any other failure is recorded and not retried. A long job works in pieces
5494
+ (docs/adr/0228): it writes a bounded batch, stops when context.timeLeft() reaches 0 or updateMany answers
5495
+ more, and returns { more: true }; the Host then calls it again at once in the same run, each call its own
5496
+ transaction, up to 50 calls or 5 minutes, and the schedule's next run continues what is left. Take what it
5497
+ stores or keys on from run.due.
5014
5498
  \`ez schedule list\` shows each schedule's next due time and last run, \`ez schedule runs <name>\` its recent runs and errors,
5015
5499
  and \`ez schedule run <name>\` runs it now (writes are real). \`ez schedule pause <name>\` stops its due times
5016
- with no push; \`ez schedule resume <name>\` starts them again from now, skipping the times missed while paused.
5500
+ with no push, and every push keeps the pause; \`ez schedule resume <name>\` starts them again from now,
5501
+ skipping the times missed while paused. Run, pause and resume are for Admins and Builders, not Limited
5502
+ Builders.
5017
5503
  Listeners receive webhooks: other services post events to the Site, verified with the secret the service
5018
5504
  issued. In listeners/stripeEvents.ts:
5019
5505
  import { listener, z } from "@ezship/react/server";
@@ -5030,13 +5516,16 @@ with Site authority, and integrations, plus event: { id, deliveryId, receivedAt,
5030
5516
  JSON (or its text), checked by the schema. Nothing imports a listener; browsers cannot post to one.
5031
5517
  After deploying, \`ez listener list\` shows the URL to give the sending service; the person who registers it
5032
5518
  runs \`ez listener secret <name>\` in a terminal with the secret the service issued (never through this
5033
- conversation); until then every delivery is refused.
5034
- [runtime] Delivery is at least once and unordered, with retries for a day: replays are refused within minutes
5035
- (standard, stripe) or days (github, or token with an idHeader), never forever. [advice] Key every once-only
5036
- effect on the payload's own id with a unique index, and pass event.deliveryId to services as the idempotency
5037
- key. \`ez listener events <name> [--dead]\`, \`show\` and \`retry\` inspect and replay events.`;
5038
-
5039
- /** `ez help api`: the Data API and its API Keys (docs/adr/0119, docs/adr/0151). */
5519
+ conversation); until then every delivery is refused. A new secret leaves the old one verifying for 24 hours
5520
+ (--overlap <hours>). Every refusal at the door is the same 404, so a missing secret looks like a bad
5521
+ signature: \`ez listener list\` counts them. A Preview has no listeners.
5522
+ [runtime] An event the schema refuses is dead at once. Delivery is at least once and unordered, with
5523
+ retries for a day: replays are refused within minutes (standard, stripe) or days (github, or token with an
5524
+ idHeader), never forever. [advice] Key every once-only effect on the payload's own id with a unique index,
5525
+ and pass event.deliveryId to services as the idempotency key. \`ez listener events <name> [--dead]\`, \`show\`
5526
+ and \`retry\` inspect and replay events.`;
5527
+
5528
+ /** `ez help api`: the Data API and its API Keys (docs/adr/0232). */
5040
5529
  const API_TOPIC = `The Data API lets another system (a sync job, a reporting tool, a script on the customer's server) read
5041
5530
  and write this Instance's data over HTTPS. Pages never use it: they have useLive and db.
5042
5531
  An Admin creates an API Key in a terminal, from any Working Copy of the Instance: \`ez key create warehouse
@@ -5055,12 +5544,15 @@ describes what it may reach. It serves the published schema as far as the App Da
5055
5544
  column is there once a Preview or Deploy has created it. _ez/api/db/<table> is the page's data API: POST <table>/query, POST
5056
5545
  <table>/aggregate, GET <table>/<id>, POST <table> (insert), PATCH and DELETE <table>/<id>, POST
5057
5546
  <table>/<id>/actions/<action>; ?why= gives a write its reason. The change feed is the History:
5058
- POST _ez/api/db/<table>_history/query {"where":{"version":{"gt":<last seen>}},"order":["version"]}.
5547
+ POST _ez/api/db/<table>_history/query {"where":{"version":{"gt":<last seen>}},"order":["version"]}. Also
5548
+ GET <table>/<id>/actions (what the key may run on the row), GET db/versions, and ?action= on an insert.
5059
5549
  Server functions are callable by a key only when they say so: serverFunction(input, handler, { api: true })
5060
5550
  [check: function-options], and only on the Sites its --sites allows. [runtime] Without --sites a key calls no
5061
5551
  functions, all means every unrestricted Site, and a Restricted Site is reached only by a key that names its id;
5062
5552
  --sites never narrows data, which groups do. POST _ez/api/sites/<site>/functions/<name> {"input": ...} answers
5063
- {"result": ...}, against that Site's deployed artifact, under the function's own access and authority. In the
5553
+ {"result": ...}, against that Site's deployed artifact, under the function's own access and authority, the
5554
+ caller rate and the Instance's budgets (ez help functions). A Site the key may not call, an archived or
5555
+ undeployed Site and a function without { api: true } all answer the same 404. In the
5064
5556
  handler a key's user is { id: "key:<name>", email: "", name, me: null, groups }. Files: POST
5065
5557
  _ez/api/attachments/<table>/<column>?name=<file> with the bytes, GET _ez/api/attachments/<id>.
5066
5558
  [runtime] Each key may make ${API_KEY_RATE.burst} requests at once, refilled at ${API_KEY_RATE.perSecond} a second (429 with Retry-After
@@ -5068,7 +5560,7 @@ past that). A key lasts ${API_KEY_DAYS.default} days by default, at most ${API_K
5068
5560
  name is never reused: to rotate, create a new key, switch the other system to it, revoke the old one.
5069
5561
  Previews have no API.`;
5070
5562
 
5071
- /** `ez help local` (ADR 0048). */
5563
+ /** `ez help local` (ADR 0235). */
5072
5564
  const LOCAL_TOPIC = `Local functions run on the Member's own computer, inside ezship Desktop, and never on the Host.
5073
5565
  In local/readEmpty.ts:
5074
5566
  import { localFunction, z } from "@ezship/react/local";
@@ -5083,7 +5575,9 @@ the Member (user), the Site (site) and desktop.dataDir, a folder the Desktop kee
5083
5575
  computer; it has no db: the page saves results with db.insert or a server function.
5084
5576
  [check] Local functions import only @ezship/react/local (localFunction, z and types), node:* built-ins (with
5085
5577
  the prefix), constants, sibling local functions and type-only global/db/types; no packages.
5086
- [runtime] One call runs at most 60 seconds. In an ordinary browser, the Studio's preview included, a call
5578
+ [runtime] One call runs at most 60 seconds; input, result and errors cross as JSON. It is arbitrary Node code,
5579
+ child processes included, on every Member's computer that opens the Site in ezship Desktop, and Members who
5580
+ share a computer share its files. In an ordinary browser, the Studio's preview included, a call
5087
5581
  fails and the Framework shows a notice that the app needs ezship Desktop; useDesktop() -> { available,
5088
5582
  version } lets a page offer manual entry instead.
5089
5583
  [advice] Use local functions for station configuration, caches, exports and exchanging files with programs on
@@ -5091,7 +5585,7 @@ that computer; the App Database stays the shared record, and nothing in a local
5091
5585
  Members or computers. Never write credentials or Host tokens to disk. Test by opening the Preview URL in
5092
5586
  ezship Desktop (ez preview prints it; ez dev keeps it fresh).`;
5093
5587
 
5094
- /** `ez help documents` (ADR 0105). */
5588
+ /** `ez help documents` (ADR 0233). */
5095
5589
  const DOCUMENTS_TOPIC = `Documents: PDFs from Global templates in \`global/documents/<Name>.tsx\` (\`ez global put documents/Invoice.tsx\`):
5096
5590
  import { document, z, Document, Page, View, Text, Image, PageNumber, asset } from "@ezship/react/pdf";
5097
5591
  export default document(
@@ -5125,6 +5619,9 @@ context and exported by @ezship/react:
5125
5619
  const r = await documents.render(Invoice, data, { filename: "invoice-1.pdf", attachTo: { table: "invoices", id, column: "pdf" } });
5126
5620
  Rendering is asynchronous: useRender(r.id) -> { status: "queued" | "rendering" | "ready" | "failed", file, error }.
5127
5621
  With attachTo the FILE column is set when the PDF is ready (useLive shows it); without it, keep r.file yourself.
5622
+ In a server function the render only joins the queue: r.status is "queued" and r.file is null there, and the
5623
+ PDF exists after the function has returned. Never build a URL from r.file in the function; a page reads the
5624
+ FILE column (or useRender) and links attachment(id). To email a PDF, see \`ez help email\`: link to that page.
5128
5625
  [runtime] Every PDF is permanent; a FILE column holding its id shares it with the Table's readers, and History
5129
5626
  keeps the ids a column held before. Input is JSON up to 1 MB; at most 200 pages.
5130
5627
  Test a deployed one: \`ez document render Invoice '<json>'\`.`;
@@ -5146,6 +5643,10 @@ The body is Markdown, never HTML: paragraphs, # headings, **bold**, *italic*, \`
5146
5643
  - and 1. lists, pipe tables (good for reports) and fenced code. The subject is one line.
5147
5644
  link("/path") is the absolute URL of a page of this Site (of your Preview, from a Preview);
5148
5645
  link("<site>", "/path") of another Site. A job has no Site of its own, so it always names one.
5646
+ link is for pages only: it is never the URL of a file, an Attachment or an API path.
5647
+ An Email carries no attachment; \`to\`, \`subject\`, \`body\` and \`button\` are the whole message. To send a file or
5648
+ a PDF (\`ez help documents\`), keep it in a FILE column of a row, link to the page that shows that row, and draw
5649
+ the download there: <a href={attachment(row.pdf)} download>. Never write "attached" in a body.
5149
5650
  [runtime] Limits: ${EMAIL_LIMITS.perInvocation} Emails per invocation, a ${EMAIL_LIMITS.subject}-character subject, a ${EMAIL_LIMITS.body / 1000} KB body; ${EMAIL_LIMITS.perDay}
5150
5651
  a day per Instance and ${EMAIL_LIMITS.perMinute} a minute per Site function or job, over which an Email is dropped (quota). A digest in a
5151
5652
  job (one Email per person, a table of their items) stays under them.
@@ -5323,14 +5824,15 @@ import CreditLimitDialog from "../components/CreditLimitDialog";
5323
5824
 
5324
5825
  /** Active customers and their credit limits; a row opens the dialog that changes one. */
5325
5826
  export default function Credit() {
5326
- const customers = useLive("customers", { where: { status: "active" }, order: ["name"] });
5827
+ const customers = useLive.query("customers", { where: { status: "active" }, order: ["name"] });
5327
5828
  const [editing, setEditing] = useState<Customer | null>(null);
5328
5829
  return (
5329
5830
  <>
5330
5831
  <PageHeader title="Credit limits" description="Open a customer to change their limit." />
5331
5832
  <Panel flush>
5332
5833
  <DataTable
5333
- rows={customers}
5834
+ rows={customers.rows}
5835
+ loading={customers.loading}
5334
5836
  columns={[
5335
5837
  { label: "Customer", cell: (c) => c.name },
5336
5838
  { label: "Limit", cell: (c) => <Money cents={c.credit_limit} />, align: "right" },
@@ -5534,6 +6036,263 @@ Site's ez check and ez preview already use your unpushed copy; ez deploy uses th
5534
6036
  computes the stored total itself rather than trusting the page's. Lib modules format nothing (no Intl on the
5535
6037
  server): the page shows cents with the starter's Money.`,
5536
6038
  },
6039
+ {
6040
+ name: "enforced-rule",
6041
+ title: "A rule nobody can get around: steps in order, enforced on the server",
6042
+ topics: ["functions", "access", "db"],
6043
+ schema: `CREATE TABLE work_steps (
6044
+ work_order TEXT,
6045
+ position INTEGER,
6046
+ title TEXT,
6047
+ held INTEGER,
6048
+ started_by MEMBER,
6049
+ started_at TIMESTAMP,
6050
+ finished_at TIMESTAMP
6051
+ );
6052
+ CREATE INDEX ON work_steps (work_order);
6053
+ `,
6054
+ global: {},
6055
+ files: {
6056
+ "functions/startStep.ts": `import { serverFunction, z } from "@ezship/react/server";
6057
+
6058
+ /** Starts a step of a work order: refused while it is on hold or an earlier step is unfinished. */
6059
+ export default serverFunction(z.object({ id: z.string().min(1) }), async ({ db, user }, input) => {
6060
+ const step = await db.get("work_steps", input.id);
6061
+ if (!step) throw new Error("This step no longer exists.");
6062
+ if (step.started_at !== null) throw new Error("This step has already started.");
6063
+ if (step.held) throw new Error("This step is on hold.");
6064
+ const unfinished = await db.count("work_steps", {
6065
+ where: { work_order: step.work_order, position: { lt: step.position ?? 0 }, finished_at: null },
6066
+ });
6067
+ if (unfinished > 0) throw new Error("Finish the earlier steps first.");
6068
+ return db.update("work_steps", step.id, { started_by: user.me, started_at: Date.now() });
6069
+ });
6070
+ `,
6071
+ "pages/steps.tsx": `import { useLive } from "@ezship/react";
6072
+ import Button from "global/Button";
6073
+ import DataTable from "global/DataTable";
6074
+ import PageHeader from "global/PageHeader";
6075
+ import Panel from "global/Panel";
6076
+ import When from "global/When";
6077
+ import startStep from "../functions/startStep";
6078
+
6079
+ /** The steps of every work order in order; Start asks the server, which refuses a step out of turn. */
6080
+ export default function Steps() {
6081
+ const steps = useLive.query("work_steps", { order: ["work_order", "position"] });
6082
+ return (
6083
+ <>
6084
+ <PageHeader title="Work steps" description="A step starts only when the ones before it are finished." />
6085
+ <Panel flush>
6086
+ <DataTable
6087
+ rows={steps.rows}
6088
+ loading={steps.loading}
6089
+ columns={[
6090
+ { label: "Work order", cell: (s) => s.work_order },
6091
+ { label: "Step", cell: (s) => s.title },
6092
+ { label: "Started", cell: (s) => <When at={s.started_at} /> },
6093
+ {
6094
+ label: "",
6095
+ cell: (s) =>
6096
+ s.started_at === null ? <Button action={() => startStep({ id: s.id })}>Start</Button> : null,
6097
+ },
6098
+ ]}
6099
+ empty="No steps yet."
6100
+ />
6101
+ </Panel>
6102
+ </>
6103
+ );
6104
+ }
6105
+ `,
6106
+ },
6107
+ notes: `The rule lives in the function, not the page: the function reads, checks and writes in one transaction that
6108
+ runs as if alone, so two people starting steps at once cannot both pass, and the page only shows the refusal
6109
+ (the starter Button's action shows what the function threw). Close the other door in global/db/access.sql
6110
+ with \`WRITE work_steps BY functions;\`: pages are then refused any write of the Table, and every change goes
6111
+ through a function that checks. The page still hides Start on a started step, but that is a convenience, never
6112
+ the rule. started_by is the function's user.me, the signed-in Member, never a name someone typed. The same
6113
+ shape holds any "never", "only" or "must": a hold that blocks a record, a gate before release, a post that
6114
+ must not run twice. When every write of a Table must pass a check, write it once as a Table rule's guard
6115
+ (global/rules/<table>.ts); when the rule is which moves a status may make, a workflow (ez help db).`,
6116
+ },
6117
+ {
6118
+ name: "function-form",
6119
+ title: "A form in a dialog that calls a server function",
6120
+ topics: ["forms", "functions"],
6121
+ schema: `CREATE TABLE visits (
6122
+ customer REFERENCES customers,
6123
+ visited_on DATE,
6124
+ minutes INTEGER,
6125
+ kind TEXT,
6126
+ notes TEXT
6127
+ );
6128
+ CREATE INDEX ON visits (customer);
6129
+ `,
6130
+ global: {},
6131
+ files: {
6132
+ "functions/logVisit.ts": `import { serverFunction, z } from "@ezship/react/server";
6133
+
6134
+ /** Logs a visit to a customer; one dated after today is refused. */
6135
+ export default serverFunction(
6136
+ z.object({
6137
+ customerId: z.string().min(1),
6138
+ visitedOn: z.string().regex(/^\\d{4}-\\d{2}-\\d{2}$/),
6139
+ minutes: z.number().int().min(1).max(600),
6140
+ kind: z.string().min(1),
6141
+ notes: z.string().max(2000),
6142
+ }),
6143
+ async ({ db }, input) => {
6144
+ // The server cannot know the viewer's day: refuse only what is after today everywhere (UTC+14).
6145
+ if (input.visitedOn > new Date(Date.now() + 14 * 3_600_000).toISOString().slice(0, 10))
6146
+ throw new Error("A visit cannot be dated after today.");
6147
+ const customer = await db.get("customers", input.customerId);
6148
+ return db.insert("visits", {
6149
+ customer: customer.id,
6150
+ visited_on: input.visitedOn,
6151
+ minutes: input.minutes,
6152
+ kind: input.kind,
6153
+ notes: input.notes,
6154
+ });
6155
+ },
6156
+ );
6157
+ `,
6158
+ "components/LogVisitDialog.tsx": `import { useState } from "react";
6159
+ import { today, type DateString } from "@ezship/react";
6160
+ import type { Customer } from "global/db/types";
6161
+ import DateInput from "global/DateInput";
6162
+ import Dialog from "global/Dialog";
6163
+ import Form from "global/Form";
6164
+ import NumberInput from "global/NumberInput";
6165
+ import SelectInput from "global/SelectInput";
6166
+ import TextArea from "global/TextArea";
6167
+ import logVisit from "../functions/logVisit";
6168
+
6169
+ /** Logs a visit to one customer: the fields, the server's refusal in place, closed when it is saved. */
6170
+ export default function LogVisitDialog({
6171
+ customer,
6172
+ onClose,
6173
+ }: {
6174
+ customer: Customer;
6175
+ onClose: () => void;
6176
+ }) {
6177
+ const [visitedOn, setVisitedOn] = useState<DateString | null>(today());
6178
+ const [minutes, setMinutes] = useState<number | null>(30);
6179
+ const [kind, setKind] = useState<string | null>(null);
6180
+ const [notes, setNotes] = useState("");
6181
+ return (
6182
+ <Dialog title="Log a visit" description={customer.name} onClose={onClose}>
6183
+ <Form
6184
+ submit="Log visit"
6185
+ columns={2}
6186
+ onCancel={onClose}
6187
+ action={async () => {
6188
+ if (!visitedOn || !minutes || !kind) throw new Error("Give the date, the minutes and the kind.");
6189
+ await logVisit({ customerId: customer.id, visitedOn, minutes, kind, notes });
6190
+ onClose();
6191
+ }}
6192
+ >
6193
+ <DateInput label="Date" value={visitedOn} onChange={setVisitedOn} required />
6194
+ <NumberInput label="Minutes" value={minutes} onChange={setMinutes} min={1} max={600} required />
6195
+ <SelectInput
6196
+ label="Kind"
6197
+ value={kind}
6198
+ onChange={setKind}
6199
+ options={["Call", "On site", "Email"]}
6200
+ required
6201
+ />
6202
+ <TextArea label="Notes" value={notes} onChange={setNotes} hint="What was agreed." />
6203
+ </Form>
6204
+ </Dialog>
6205
+ );
6206
+ }
6207
+ `,
6208
+ },
6209
+ notes: `Uses the customers Table of record-list. Form runs its action on submit, keeps the submit button busy while
6210
+ it runs and shows what it throws above the fields, the function's own refusal included, so the component
6211
+ holds no error state, no pending flag and no try/catch. The typed inputs carry their label, hint and error
6212
+ and answer the value in its type (a number or null, a DateString or null), so no input, select or textarea
6213
+ is written by hand and nothing is parsed. Render it where a button opens it: {logging ? <LogVisitDialog
6214
+ customer={customer} onClose={() => setLogging(false)} /> : null}. A form that only writes one Table's row
6215
+ needs none of this: RecordForm draws it from the schema (record-form).`,
6216
+ },
6217
+ {
6218
+ name: "board",
6219
+ title: "A page of totals, filters and a board of cards",
6220
+ topics: ["data", "files"],
6221
+ schema: null,
6222
+ global: {},
6223
+ files: {
6224
+ "pages/pipeline.tsx": `import { useState } from "react";
6225
+ import { useLive } from "@ezship/react";
6226
+ import Badge from "global/Badge";
6227
+ import Board from "global/Board";
6228
+ import BoardColumn from "global/BoardColumn";
6229
+ import Button from "global/Button";
6230
+ import Card from "global/Card";
6231
+ import Money from "global/Money";
6232
+ import PageHeader from "global/PageHeader";
6233
+ import SearchBox from "global/SearchBox";
6234
+ import Stat from "global/Stat";
6235
+ import Stats from "global/Stats";
6236
+ import Toolbar from "global/Toolbar";
6237
+
6238
+ /** Customers by status: how many in each, and a column of cards for each, searched by name. */
6239
+ export default function Pipeline() {
6240
+ const [q, setQ] = useState("");
6241
+ const counts = useLive.aggregate("customers", { group: ["status"] });
6242
+ const count = (status: string) => counts.rows.find((r) => r.group.status === status)?.count ?? 0;
6243
+ const like = q ? { name: { contains: q } } : {};
6244
+ const leads = useLive.query("customers", { where: { status: "lead", ...like }, order: ["name"], limit: 50 });
6245
+ const active = useLive.query("customers", { where: { status: "active", ...like }, order: ["name"], limit: 50 });
6246
+ const closed = useLive.query("customers", { where: { status: "closed", ...like }, order: ["name"], limit: 50 });
6247
+ const columns = [
6248
+ { title: "Leads", found: leads },
6249
+ { title: "Active", found: active },
6250
+ { title: "Closed", found: closed },
6251
+ ];
6252
+ return (
6253
+ <div className="stack">
6254
+ <PageHeader title="Pipeline" description="Every customer by where they stand." />
6255
+ <Stats>
6256
+ <Stat label="Leads" value={count("lead")} tone="info" />
6257
+ <Stat label="Active" value={count("active")} tone="ok" />
6258
+ <Stat label="Closed" value={count("closed")} />
6259
+ </Stats>
6260
+ <Toolbar aside={<Button to="/customers/new" variant="primary">New customer</Button>}>
6261
+ <SearchBox value={q} onChange={setQ} hideLabel />
6262
+ </Toolbar>
6263
+ <Board>
6264
+ {columns.map((column) => (
6265
+ <BoardColumn
6266
+ key={column.title}
6267
+ title={column.title}
6268
+ count={column.found.rows.length}
6269
+ hint={column.found.truncated ? "Showing the first 50." : undefined}
6270
+ empty="No customers here."
6271
+ >
6272
+ {column.found.rows.map((c) => (
6273
+ <Card
6274
+ key={c.id}
6275
+ to={\`/customers/\${c.id}\`}
6276
+ title={c.name}
6277
+ aside={c.vip ? <Badge value="VIP" tone="warn" /> : null}
6278
+ meta={c.email}
6279
+ >
6280
+ <Money cents={c.credit_limit} />
6281
+ </Card>
6282
+ ))}
6283
+ </BoardColumn>
6284
+ ))}
6285
+ </Board>
6286
+ </div>
6287
+ );
6288
+ }
6289
+ `,
6290
+ },
6291
+ notes: `Uses the customers Table of record-list. Stats, Toolbar, Board, BoardColumn and Card are the starter's layout:
6292
+ a row of tiles of one width, the controls above a list with a button at the far end, and columns of cards that
6293
+ wrap on a narrow screen, so the page writes no class and no CSS of its own. The totals are one aggregate, which
6294
+ is complete; each column is its own query with the search in its where and says when it stopped at its limit.`,
6295
+ },
5537
6296
  ]),
5538
6297
  );
5539
6298
 
@@ -5560,12 +6319,13 @@ against the starter Global Workspace). They share one customers Table, declared
5560
6319
 
5561
6320
  ${RECIPES.map(recipeText).join("\n\n")}`;
5562
6321
 
5563
- /** `ez help access`: the doors around the App Database's rows (ADRs 0036, 0098, 0101, 0110). */
6322
+ /** `ez help access`: the doors around the App Database's rows (ADRs 0203 and 0225). */
5564
6323
  const accessTopic =
5565
6324
  () => `Access: who opens a Site, who reads and writes which rows, who runs which code.
5566
6325
  Every Site and Preview requires a signed-in active Member; Builders are Members too. An Admin may restrict a
5567
6326
  Site to allow-lists and groups (\`ez site access\`); the Admin who restricts it stays on its lists, so
5568
6327
  \`ez site access restrict\` alone makes an app theirs only. Sign-in is the platform's: never build a login page.
6328
+ Members sign in with an emailed code, or with a username and password they set on that page.
5569
6329
  Rows: global/db/access.sql is the one place that says who reads and writes which rows. [runtime] The Host
5570
6330
  applies it to every page, function, job and attachment request, for deployed Sites and Previews alike, from
5571
6331
  the moment an Admin pushes it (ez help lifecycle); a row a Member may not read is "Not found".
@@ -5603,7 +6363,7 @@ export const HELP_TOPICS = Object.freeze([
5603
6363
  {
5604
6364
  name: "recipes",
5605
6365
  summary:
5606
- "complete examples: a searchable list, a record form, a modal save, an external call, shared logic",
6366
+ "complete examples: a searchable list, a record form, a modal save, a form that calls a function, a board of cards, an external call, shared logic, an enforced rule",
5607
6367
  text: () => RECIPES_TOPIC,
5608
6368
  },
5609
6369
  {
@@ -5725,6 +6485,10 @@ export const COMMANDS = [
5725
6485
  usage: "ez function call <name> <json> [--preview <name>]",
5726
6486
  help: "invoke a Site function from its deployment or your Preview; writes are real",
5727
6487
  },
6488
+ {
6489
+ usage: "ez function ls",
6490
+ help: "the server functions in this working copy; one is callable once a Preview or a Deploy has built it",
6491
+ },
5728
6492
  {
5729
6493
  usage: "ez schedule list",
5730
6494
  help: "the Instance's pushed global/schedules.json: each schedule's cron, job, next due time and last run",
@@ -5767,7 +6531,7 @@ export const COMMANDS = [
5767
6531
  },
5768
6532
  {
5769
6533
  usage: "ez help [<topic> | all]",
5770
- help: "the short guide every task needs; a topic adds detail (lifecycle, files, recipes, data, forms, frame, functions, access, integrations, jobs, local, documents, db, rules, commands); all prints everything",
6534
+ help: "the short guide every task needs; a topic adds detail (lifecycle, files, recipes, data, forms, frame, functions, access, integrations, jobs, api, local, documents, email, db, rules, commands); all prints everything",
5771
6535
  },
5772
6536
  {
5773
6537
  usage: "ez status",
@@ -5803,7 +6567,7 @@ export const COMMANDS = [
5803
6567
  help: "your previews of this site: name, status, URL, last activity; --others lists the other Builders' previews of it instead (who, name, what it builds, status, last activity; never their URLs)",
5804
6568
  },
5805
6569
  {
5806
- usage: "ez preview delete|rm [<name>]",
6570
+ usage: "ez preview delete [<name>]",
5807
6571
  help: "delete a preview (the default one when no name is given)",
5808
6572
  },
5809
6573
  {
@@ -5818,7 +6582,6 @@ export const COMMANDS = [
5818
6582
  usage: "ez delete <path>",
5819
6583
  help: `delete a file (${MAIN_FILE} and ${CONTEXT_FILE} cannot be deleted)`,
5820
6584
  },
5821
- { usage: "ez rm <path>", help: "alias for delete" },
5822
6585
  { usage: "ez mv <from> <to>", help: "rename a file" },
5823
6586
  {
5824
6587
  usage: "ez config",
@@ -5842,7 +6605,6 @@ export const COMMANDS = [
5842
6605
  usage: "ez site archive <id>",
5843
6606
  help: "admins: archive a site, retaining its files, data and id",
5844
6607
  },
5845
- { usage: "ez site rm <id>", help: "alias for site archive" },
5846
6608
  {
5847
6609
  usage: "ez site access",
5848
6610
  help: "who may open this site: every builder and member, or the allow-lists",
@@ -5852,11 +6614,11 @@ export const COMMANDS = [
5852
6614
  help: "admins: switch between the allow-lists and everyone in the instance; whoever restricts a site stays on its lists",
5853
6615
  },
5854
6616
  {
5855
- usage: "ez site access add|remove|rm builder|user <who>",
6617
+ usage: "ez site access add|remove builder|user <who>",
5856
6618
  help: "admins: edit the allow-lists (who is an id or email)",
5857
6619
  },
5858
6620
  {
5859
- usage: "ez site access add|remove|rm group <name>",
6621
+ usage: "ez site access add|remove group <name>",
5860
6622
  help: "admins: let a group's members (implied groups included) open the restricted site, or stop",
5861
6623
  },
5862
6624
  {
@@ -5872,7 +6634,7 @@ export const COMMANDS = [
5872
6634
  help: "admins: change a builder's role (who is an id or email); limited builders neither push global nor create sites",
5873
6635
  },
5874
6636
  {
5875
- usage: "ez builder remove|rm <who>",
6637
+ usage: "ez builder remove <who>",
5876
6638
  help: "admins: remove a builder (and their membership) from the instance",
5877
6639
  },
5878
6640
  {
@@ -5885,7 +6647,7 @@ export const COMMANDS = [
5885
6647
  },
5886
6648
  { usage: "ez user block <who>", help: "block a member (who is an id or email)" },
5887
6649
  { usage: "ez user unblock <who>", help: "unblock a member" },
5888
- { usage: "ez user remove|rm <who>", help: "remove a member from the instance" },
6650
+ { usage: "ez user remove <who>", help: "remove a member from the instance" },
5889
6651
  {
5890
6652
  usage: "ez user group add|remove <who> <group>",
5891
6653
  help: "admins: put a member in a group, or take them out; access rules name groups as group(<name>); server code with Site authority assigns the groups access.sql declares; ez-admin and ez-builder follow the Builder roster and are never assigned",
@@ -5895,21 +6657,17 @@ export const COMMANDS = [
5895
6657
  help: 'admins: upload an image, video or document once for the whole instance; site code then says asset("<name>")',
5896
6658
  },
5897
6659
  { usage: "ez asset ls", help: "the instance's assets: name, type, size" },
5898
- {
5899
- usage: "ez asset delete|rm <name> [--force]",
5900
- help: "disabled: assets cannot be deleted, even with --force; upload with a new name",
5901
- },
5902
6660
  {
5903
6661
  usage: "ez audit [--site <id>] [--kind <kind>] [--limit N] [--before <id>]",
5904
6662
  help: "who did what in this instance, newest first",
5905
6663
  },
5906
6664
  {
5907
6665
  usage: "ez db tables",
5908
- help: "every table in the app database: columns, indexes, rows, which sites declare it",
6666
+ help: "every table in the app database: columns, indexes, rows",
5909
6667
  },
5910
6668
  {
5911
6669
  usage: "ez db schema",
5912
- help: "the live schema as nullable CREATE TABLE statements, to consolidate into global/db/schema.sql",
6670
+ help: "the live schema as CREATE TABLE statements",
5913
6671
  },
5914
6672
  {
5915
6673
  usage: "ez db sql <statement>",
@@ -5951,7 +6709,7 @@ export const COMMANDS = [
5951
6709
  {
5952
6710
  usage:
5953
6711
  "ez integration set <name> (--preset <preset> | --origin <url> --oauth <grant> --token-url <url> [--authorize-url <url>] [--revoke-url <url>] [--client-auth basic|post] [--user <user>]) --client-id <id> [--scope <scopes>]",
5954
- help: "admins: an OAuth credential (presets: quickbooks), the client secret (then a password grant's password) from stdin; stored only, since OAuth flows are not built yet (ADR 0140)",
6712
+ help: "admins: an OAuth credential (presets: quickbooks), the client secret (then a password grant's password) from stdin; stored only, since OAuth flows are not built yet (ADR 0231)",
5955
6713
  },
5956
6714
  {
5957
6715
  usage:
@@ -6016,7 +6774,7 @@ export const COMMANDS = [
6016
6774
  function formatHelp(commands) {
6017
6775
  const width = Math.max(...commands.map((c) => c.usage.length));
6018
6776
  const lines = commands.map((c) => ` ${c.usage.padEnd(width)} ${c.help}`);
6019
- return `Commands (add --json to any of them for machine-readable output; rm is a compatibility alias):\n${lines.join("\n")}`;
6777
+ return `Commands (add --json to any of them for machine-readable output):\n${lines.join("\n")}`;
6020
6778
  }
6021
6779
 
6022
6780
  /** @type {typeof import("./commands.d.mts").HELP} */
@@ -6094,7 +6852,7 @@ export const pinnedGlobalPath = (path) =>
6094
6852
  path !== TYPES_FILE;
6095
6853
 
6096
6854
  /**
6097
- * A Global push's two kinds of change (docs/adr/0096): Live ones took effect for every deployed Site at once;
6855
+ * A Global push's two kinds of change (docs/adr/0224): Live ones took effect for every deployed Site at once;
6098
6856
  * the rest reach each Site at its next Preview or Deploy.
6099
6857
  * @param {import("./types.d.mts").PushResult} result
6100
6858
  */
@@ -6176,7 +6934,7 @@ function liveLines(result) {
6176
6934
  }
6177
6935
 
6178
6936
  /**
6179
- * What changed access rules do to Members' rows (docs/adr/0098), Member by Member, the first 20 per rule.
6937
+ * What changed access rules do to Members' rows (docs/adr/0225), Member by Member, the first 20 per rule.
6180
6938
  * @param {import("./types.d.mts").PushResult} result
6181
6939
  */
6182
6940
  function reportLines(result) {
@@ -6205,7 +6963,7 @@ function reportLines(result) {
6205
6963
 
6206
6964
  /**
6207
6965
  * A Site's Check and Preview build with the Global Working Copy beside it, unpushed edits included (ADR
6208
- * 0021); a failure in global/ says so, since the edit may be another agent's in a shared folder.
6966
+ * 0217); a failure in global/ says so, since the edit may be another agent's in a shared folder.
6209
6967
  * @param {Record<string, string> | undefined} globalCopy @param {import("./commands.d.mts").Diagnostic[]} diagnostics
6210
6968
  */
6211
6969
  const globalCopyNote = (globalCopy, diagnostics) =>
@@ -6216,7 +6974,7 @@ const globalCopyNote = (globalCopy, diagnostics) =>
6216
6974
  const versionLine = (v) => `v${v.n}${v.by ? ` by ${v.by}` : ""}${v.at ? ` ${ago(v.at)}` : ""}`;
6217
6975
 
6218
6976
  /**
6219
- * After a write to db/schema.sql or a workflow (docs/adr/0103): rewrite db/types.d.ts when the declaration
6977
+ * After a write to db/schema.sql or a workflow (docs/adr/0227): rewrite db/types.d.ts when the declaration
6220
6978
  * parses (a parse error is reported by check and push, not here).
6221
6979
  * @param {Workspace} ws @param {string} path
6222
6980
  */
@@ -6231,7 +6989,7 @@ async function regenerateTypes(ws, path) {
6231
6989
  }
6232
6990
 
6233
6991
  /**
6234
- * Before a check or push (docs/adr/0108): rewrite CONTEXT.md's file inventory when it has text and its block
6992
+ * Before a check or push (docs/adr/0215): rewrite CONTEXT.md's file inventory when it has text and its block
6235
6993
  * is missing or stale (an empty CONTEXT.md is the \`context\` error's, not this).
6236
6994
  * @param {Workspace} ws
6237
6995
  */
@@ -6245,28 +7003,24 @@ async function regenerateInventory(ws) {
6245
7003
 
6246
7004
  /**
6247
7005
  * `ez status`'s schema lines: the Global Working Copy's changes relative to the live App Database.
6248
- * @param {Workspace} ws @param {Record<string,string>} files @param {string} instance @param {string} siteId
7006
+ * @param {Workspace} ws @param {Record<string,string>} files @param {string} instance
6249
7007
  */
6250
- async function schemaStatus(ws, files, instance, siteId) {
7008
+ async function schemaStatus(ws, files, instance) {
6251
7009
  if (!(SCHEMA_FILE in files)) return null;
6252
7010
  const decl = parseGlobalSchema(files[SCHEMA_FILE]);
6253
7011
  if ("error" in decl) {
6254
7012
  const message = `${SCHEMA_FILE} line ${decl.line}: ${decl.error}`;
6255
7013
  return { lines: [`schema: ${message}`], data: { ok: false, error: message } };
6256
7014
  }
6257
- const plan = planSchema(await ws.dbSchema(), decl, instance, siteId);
7015
+ const plan = planSchema(await ws.dbSchema(), decl, instance);
6258
7016
  if ("error" in plan)
6259
7017
  return { lines: [`schema: ${plan.error}`], data: { ok: false, error: plan.error } };
6260
7018
  const { created, added, indexed } = plan.summary;
6261
7019
  const lines = [];
6262
7020
  if (plan.conflicts.length > 0) {
6263
- lines.push(
6264
- "schema: conflicts with other sites; deploy would be refused until they change their declaration",
6265
- );
7021
+ lines.push("schema: conflicts with the App Database; deploy would be refused");
6266
7022
  for (const c of plan.conflicts)
6267
- lines.push(
6268
- ` ${c.table}.${c.column}: you declare ${c.mine}; ${c.site ? `site "${c.site}" declares ${c.theirs}` : `it is ${c.theirs}`}`,
6269
- );
7023
+ lines.push(` ${c.table}.${c.column}: declared ${c.mine}; it is ${c.theirs}`);
6270
7024
  } else if (created.length + added.length + indexed.length === 0) {
6271
7025
  lines.push("schema: up to date");
6272
7026
  } else {
@@ -6280,14 +7034,14 @@ async function schemaStatus(ws, files, instance, siteId) {
6280
7034
  }
6281
7035
 
6282
7036
  /**
6283
- * What the Site's next deploy brings in from the Global Workspace (docs/adr/0141): the pushed Global files that
7037
+ * What the Site's next deploy brings in from the Global Workspace (docs/adr/0211): the pushed Global files that
6284
7038
  * changed since the Version its live app was built with, as the Host recorded that deploy. A deploy builds the
6285
7039
  * pushed Global, so unpushed Global changes are not among them.
6286
7040
  * @type {typeof import("./commands.d.mts").globalSinceDeploy}
6287
7041
  */
6288
7042
  export async function globalSinceDeploy(site, global) {
6289
7043
  const deployed = site.deployedGlobal;
6290
- if (site.deployedAt === null || typeof deployed !== "number") return null;
7044
+ if (site.deployedAt === null || deployed === null) return null;
6291
7045
  const newest = (await global.remoteStatus()).version.n;
6292
7046
  if (newest <= deployed)
6293
7047
  return { deployed, current: newest, paths: { added: [], changed: [], removed: [] } };
@@ -6340,7 +7094,7 @@ export function describeCommand(argv) {
6340
7094
  const [cmd, a, b] = argv;
6341
7095
  switch (cmd) {
6342
7096
  case "function":
6343
- return `Called function ${b ?? ""}`.trim();
7097
+ return a === "ls" ? "Listed the functions" : `Called function ${b ?? ""}`.trim();
6344
7098
  case "schedule":
6345
7099
  return a === "run"
6346
7100
  ? `Ran schedule ${b ?? ""}`.trim()
@@ -6371,7 +7125,7 @@ export function describeCommand(argv) {
6371
7125
  : "Formatted the working copy";
6372
7126
  case "preview":
6373
7127
  if (a === "ls") return "Listed the previews";
6374
- if (a === "delete" || a === "rm") return `Deleted the ${b ?? ""} preview`.trim();
7128
+ if (a === "delete") return `Deleted the ${b ?? ""} preview`.trim();
6375
7129
  return "Previewed the working copy";
6376
7130
  case "link":
6377
7131
  if (a !== "--preview") return "Made a sign-in link to the app";
@@ -6385,7 +7139,6 @@ export function describeCommand(argv) {
6385
7139
  case "edit":
6386
7140
  return `Edited ${a ?? ""}`.trim();
6387
7141
  case "delete":
6388
- case "rm":
6389
7142
  return `Deleted ${a ?? ""}`.trim();
6390
7143
  case "mv":
6391
7144
  return `Renamed ${a ?? ""} to ${b ?? ""}`.trim();
@@ -6398,13 +7151,13 @@ export function describeCommand(argv) {
6398
7151
  case "site":
6399
7152
  if (a === "ls") return "Listed the instance's sites";
6400
7153
  if (a === "create") return `Created site ${b ?? ""}`.trim();
6401
- if (a === "archive" || a === "rm") return `Archived site ${b ?? ""}`.trim();
7154
+ if (a === "archive") return `Archived site ${b ?? ""}`.trim();
6402
7155
  if (a === "access") {
6403
7156
  const [, , verb, , who] = argv;
6404
7157
  if (verb === "restrict") return "Restricted the site";
6405
7158
  if (verb === "open") return "Opened the site to the instance";
6406
7159
  if (verb === "add") return `Allowed ${who ?? ""}`.trim();
6407
- if (verb === "remove" || verb === "rm") return `Disallowed ${who ?? ""}`.trim();
7160
+ if (verb === "remove") return `Disallowed ${who ?? ""}`.trim();
6408
7161
  return "Read who may open the site";
6409
7162
  }
6410
7163
  return `Ran ez ${argv.join(" ")}`.trim();
@@ -6413,7 +7166,7 @@ export function describeCommand(argv) {
6413
7166
  case "builder":
6414
7167
  if (a === "add") return `Invited ${b ?? ""}`.trim();
6415
7168
  if (a === "set-role") return `Changed ${b ?? ""}'s role`.trim();
6416
- if (a === "remove" || a === "rm") return `Removed ${b ?? ""}`.trim();
7169
+ if (a === "remove") return `Removed ${b ?? ""}`.trim();
6417
7170
  return `Ran ez ${argv.join(" ")}`.trim();
6418
7171
  case "users":
6419
7172
  return "Listed the app members";
@@ -6421,7 +7174,7 @@ export function describeCommand(argv) {
6421
7174
  if (a === "add") return `Added ${b ?? ""}`.trim();
6422
7175
  if (a === "block") return `Blocked ${b ?? ""}`.trim();
6423
7176
  if (a === "unblock") return `Unblocked ${b ?? ""}`.trim();
6424
- if (a === "remove" || a === "rm") return `Removed ${b ?? ""}`.trim();
7177
+ if (a === "remove") return `Removed ${b ?? ""}`.trim();
6425
7178
  return `Ran ez ${argv.join(" ")}`.trim();
6426
7179
  case "audit":
6427
7180
  return "Read the instance's audit trail";
@@ -6452,7 +7205,6 @@ export function describeCommand(argv) {
6452
7205
  : "Listed the support requests";
6453
7206
  case "asset":
6454
7207
  if (a === "add") return `Uploaded asset ${b ?? ""}`.trim();
6455
- if (a === "delete" || a === "rm") return `Deleted asset ${b ?? ""}`.trim();
6456
7208
  return "Listed the instance's assets";
6457
7209
  case "db":
6458
7210
  if (a === "tables") return "Listed the app database's tables";
@@ -6516,35 +7268,6 @@ export async function runCommand(ws, argv, stdin) {
6516
7268
  : text;
6517
7269
  }
6518
7270
 
6519
- const MISSING_EXPORT_RE =
6520
- /^TS(?:2305|2724): (?:Module )?'"(@ezship\/react(?:\/server|\/local)?)"' has no exported member (?:named )?'([\w$]+)'/;
6521
-
6522
- /**
6523
- * The Host's Builder says the Framework lacks a name this client's editor declarations export: the Host runs
6524
- * an older Framework than this \`ez\` (docs/adr/0078). Says so on that diagnostic instead of leaving a Builder
6525
- * to work around an editor and a checker that disagree.
6526
- * @param {import("./commands.d.mts").Workspace} ws
6527
- */
6528
- const noteSkew =
6529
- (ws) =>
6530
- /** @param {{ diagnostics: import("./commands.d.mts").Diagnostic[] }} result */
6531
- async (result) => {
6532
- const missing = result.diagnostics.filter((d) => MISSING_EXPORT_RE.test(d.message));
6533
- if (!missing.length || !ws.editorExports) return result;
6534
- /** @type {Record<string, string[]>} */
6535
- const exported = await ws.editorExports().catch(() => ({}));
6536
- return {
6537
- diagnostics: result.diagnostics.map((d) => {
6538
- const m = MISSING_EXPORT_RE.exec(d.message);
6539
- if (!m || !exported[m[1]]?.includes(m[2])) return d;
6540
- return {
6541
- ...d,
6542
- message: `${d.message}\nYour editor's declarations have ${m[2]}, so this Host runs an older Framework than your ez: don't use ${m[2]} here, or ask the Host's operator to update it.`,
6543
- };
6544
- }),
6545
- };
6546
- };
6547
-
6548
7271
  /**
6549
7272
  * A command that failed with a result: `message` is what to print, `data` what `--json` prints instead. The
6550
7273
  * command still fails (`ez` exits non-zero), and under --json the message is the JSON.
@@ -6734,7 +7457,22 @@ async function execute(ws, argv, stdin) {
6734
7457
  return out(renderLine(row), row);
6735
7458
  }
6736
7459
  case "function": {
6737
- const syntax = "ez function call <name> <json> [--preview <name>]";
7460
+ const syntax = "ez function call <name> <json> [--preview <name>] | ez function ls";
7461
+ /** The working copy's server functions, by name. */
7462
+ const written = async () =>
7463
+ Object.keys(await ws.files())
7464
+ .map((p) => functionName(p))
7465
+ .filter((n) => n !== null)
7466
+ .sort();
7467
+ if (args[0] === "ls" && args.filter((a) => a !== "--json").length === 1) {
7468
+ const names = await written();
7469
+ return out(
7470
+ names.length
7471
+ ? `${names.join("\n")}\nA function runs from the live Version or a Preview, never from unpushed files: \`ez preview\`, then \`ez function call <name> '<json>' --preview <name>\`.`
7472
+ : `This working copy has no server functions (${FUNCTIONS_DIR}<name>.ts).`,
7473
+ names,
7474
+ );
7475
+ }
6738
7476
  if (
6739
7477
  args[0] !== "call" ||
6740
7478
  !FUNCTION_NAME_RE.test(args[1] ?? "") ||
@@ -6748,7 +7486,18 @@ async function execute(ws, argv, stdin) {
6748
7486
  } catch {
6749
7487
  throw usage(`${syntax}: input must be JSON`);
6750
7488
  }
6751
- const result = await ws.callFunction(args[1], input, args[4]);
7489
+ const result = await ws.callFunction(args[1], input, args[4]).catch(async (e) => {
7490
+ // "No such function." is three things to the caller: no such file, a file nothing has built yet, or a
7491
+ // Preview that was built before it. The working copy says which.
7492
+ if (!(e instanceof Error) || !/No such function/.test(e.message)) throw e;
7493
+ const names = await written().catch(() => null);
7494
+ if (!names) throw e;
7495
+ const where = args[4] ? `the Preview ${args[4]}` : "the live Version";
7496
+ e.message = names.includes(args[1])
7497
+ ? `${e.message} ${FUNCTIONS_DIR}${args[1]}.ts is in this working copy, but ${where} was built without it: run \`ez preview\`, then \`ez function call ${args[1]} '<json>' --preview <name>\` (\`ez preview ls\` names it)${args[4] ? "" : ", or push and deploy"}.`
7498
+ : `${e.message} This working copy has no ${FUNCTIONS_DIR}${args[1]}.ts${names.length ? `; its functions: ${names.join(", ")}` : ""}.`;
7499
+ throw e;
7500
+ });
6752
7501
  return out(JSON.stringify(result.result, null, 2), result);
6753
7502
  }
6754
7503
  case "schedule": {
@@ -6767,7 +7516,6 @@ async function execute(ws, argv, stdin) {
6767
7516
  s.name,
6768
7517
  s.cron,
6769
7518
  s.job,
6770
- // An older Host answers no `paused`.
6771
7519
  s.paused ? `paused by ${s.paused.by}` : `next ${utcMinute(s.next)}`,
6772
7520
  s.last ? `last ${s.last.status} ${utcMinute(s.last.due)}` : "never run",
6773
7521
  ].join(" "),
@@ -6837,9 +7585,9 @@ async function execute(ws, argv, stdin) {
6837
7585
  for (const p of changes.deleted) lines.push(` deleted ${p}`);
6838
7586
  const schema = global
6839
7587
  ? null
6840
- : await schemaStatus(ws, (await ws.globalFiles?.()) ?? {}, remote.instance, remote.id);
7588
+ : await schemaStatus(ws, (await ws.globalFiles?.()) ?? {}, remote.instance);
6841
7589
  if (schema) lines.push(...schema.lines);
6842
- // What the deploy also brings in from the Global Workspace (docs/adr/0141); never fails the status.
7590
+ // What the deploy also brings in from the Global Workspace (docs/adr/0211); never fails the status.
6843
7591
  const brings = global
6844
7592
  ? null
6845
7593
  : await (async () => {
@@ -6921,7 +7669,7 @@ async function execute(ws, argv, stdin) {
6921
7669
  throw usage('ez push [-m "<message>"] [--prune] [--force]');
6922
7670
  const checked = messageText(message, "The message");
6923
7671
  if ("error" in checked) throw new Error(checked.error);
6924
- // --dry-run reports a Global push's Live changes (docs/adr/0096). A Site push has none, and ignoring the
7672
+ // --dry-run reports a Global push's Live changes (docs/adr/0224). A Site push has none, and ignoring the
6925
7673
  // flag would push for real, so it is refused before anything is sent.
6926
7674
  if (!global && flags.has("--dry-run"))
6927
7675
  throw new Error(
@@ -6936,7 +7684,7 @@ async function execute(ws, argv, stdin) {
6936
7684
  for (const [p, c] of Object.entries(files))
6937
7685
  if (c.length > MAX_FILE_BYTES)
6938
7686
  throw new Error(`${p} is too large (max ${MAX_FILE_BYTES} bytes)`);
6939
- // A Global push first checks every Site against these files (docs/adr/0078); --force pushes regardless.
7687
+ // A Global push first checks every Site against these files (docs/adr/0236); --force pushes regardless.
6940
7688
  if (global && !flags.has("--force")) {
6941
7689
  const { diagnostics } = await ws.check(files).catch((error) => {
6942
7690
  throw new Error(
@@ -6952,7 +7700,7 @@ async function execute(ws, argv, stdin) {
6952
7700
  // A file this copy pulled and then deleted is deleted on the shared side too; --prune additionally
6953
7701
  // deletes shared files this copy never tracked (pushed by someone else since the pull).
6954
7702
  const deleted = localChanges(files, await ws.pulled()).deleted;
6955
- // A Global push's Live changes (docs/adr/0096): --dry-run reports them without saving,
7703
+ // A Global push's Live changes (docs/adr/0224): --dry-run reports them without saving,
6956
7704
  // --acknowledge-exposure accepts rules that let Members read more, --force is an Admin's (server-checked).
6957
7705
  /** @type {{ message?: string, dryRun?: boolean, acknowledgeExposure?: boolean, force?: boolean }} */
6958
7706
  const options = {};
@@ -6979,9 +7727,9 @@ async function execute(ws, argv, stdin) {
6979
7727
  const lines = [
6980
7728
  `Deployed ${plural(r.files.length, "file")} at ${new Date(r.deployedAt).toLocaleString()}${r.global ? ` with global v${r.global}` : ""}.${r.appUrl ? ` ${r.appUrl}` : ""}`,
6981
7729
  ];
6982
- for (const t of r.schema?.created ?? []) lines.push(`created table ${t}`);
6983
- for (const c of r.schema?.added ?? []) lines.push(`added column ${c}`);
6984
- for (const i of r.schema?.indexed ?? []) lines.push(`indexed ${i}`);
7730
+ for (const t of r.schema.created) lines.push(`created table ${t}`);
7731
+ for (const c of r.schema.added) lines.push(`added column ${c}`);
7732
+ for (const i of r.schema.indexed) lines.push(`indexed ${i}`);
6985
7733
  for (const w of r.warnings ?? []) lines.push(`warning: ${w}`);
6986
7734
  return out(lines.join("\n"), r);
6987
7735
  }
@@ -6989,7 +7737,7 @@ async function execute(ws, argv, stdin) {
6989
7737
  case "versions": {
6990
7738
  const rows = await ws.listVersions();
6991
7739
  if (rows.length === 0) return out("No versions yet. Push first.", rows);
6992
- // A Site's rows say which Version Members see and which a deploy shipped before (docs/adr/0141).
7740
+ // A Site's rows say which Version Members see and which a deploy shipped before (docs/adr/0211).
6993
7741
  /** @param {Version} v */
6994
7742
  const shipped = (v) =>
6995
7743
  v.live ? " [live]" : v.deployedAt ? ` [deployed ${ago(v.deployedAt)}]` : "";
@@ -7007,12 +7755,10 @@ async function execute(ws, argv, stdin) {
7007
7755
  await regenerateInventory(ws);
7008
7756
  Object.assign(files, await ws.files());
7009
7757
  const local = global ? checkGlobalStructure(files) : checkStructure(files);
7010
- // A Site checks against the Global Working Copy its Preview would upload (ADR 0021).
7758
+ // A Site checks against the Global Working Copy its Preview would upload (ADR 0217).
7011
7759
  const globalCopy = global || local.length > 0 ? undefined : await ws.globalFiles?.();
7012
7760
  const { diagnostics } =
7013
- local.length > 0
7014
- ? { diagnostics: local }
7015
- : await ws.check(files, globalCopy).then(noteSkew(ws));
7761
+ local.length > 0 ? { diagnostics: local } : await ws.check(files, globalCopy);
7016
7762
  const entries = checkEntries(diagnostics);
7017
7763
  if (diagnostics.some((d) => d.severity !== 2))
7018
7764
  throw new CommandFailure(
@@ -7025,7 +7771,7 @@ async function execute(ws, argv, stdin) {
7025
7771
  );
7026
7772
  }
7027
7773
 
7028
- // `ez format` (docs/adr/0089): the Host formats the .ts/.tsx files and answers the ones that change; a file
7774
+ // `ez format` (docs/adr/0237): the Host formats the .ts/.tsx files and answers the ones that change; a file
7029
7775
  // that does not parse stops it before anything is written. --check writes nothing and fails on a change.
7030
7776
  case "format": {
7031
7777
  if (pos.length || [...flags].some((f) => f !== "--check")) throw usage("ez format [--check]");
@@ -7053,7 +7799,7 @@ async function execute(ws, argv, stdin) {
7053
7799
  );
7054
7800
  }
7055
7801
 
7056
- // `ez preview` (docs/adr/0013): the working copy (or a retained Version) built on the Host and served at a
7802
+ // `ez preview` (docs/adr/0212): the working copy (or a retained Version) built on the Host and served at a
7057
7803
  // private URL against the live data. The name defaults to the client's (`ws.previewName`: the CLI's folder,
7058
7804
  // the studio's remembered name). A successful upload is also a check; a failed one keeps the last good build.
7059
7805
  case "preview": {
@@ -7070,7 +7816,7 @@ async function execute(ws, argv, stdin) {
7070
7816
  else if (!args[i].startsWith("--")) words.push(args[i]);
7071
7817
  }
7072
7818
  const [sub, ...rest] = words;
7073
- // Other Builders' Previews of this Site (docs/adr/0141): who is changing it, never their URLs.
7819
+ // Other Builders' Previews of this Site (docs/adr/0211): who is changing it, never their URLs.
7074
7820
  if (sub === "ls" && others) {
7075
7821
  const rows = await ws.listOtherPreviews();
7076
7822
  if (rows.length === 0) return out("No other Builder has a preview of this site.", rows);
@@ -7107,7 +7853,7 @@ async function execute(ws, argv, stdin) {
7107
7853
  throw usage("ez preview --name <name> (this client has no default preview name)");
7108
7854
  return name;
7109
7855
  };
7110
- if (sub === "delete" || sub === "rm") {
7856
+ if (sub === "delete") {
7111
7857
  const name = rest[0] ?? (await defaultName());
7112
7858
  const why = previewNameError(name);
7113
7859
  if (why) throw new Error(why);
@@ -7138,9 +7884,9 @@ async function execute(ws, argv, stdin) {
7138
7884
  });
7139
7885
  }
7140
7886
  const lines = [];
7141
- for (const t of result.schema?.created ?? []) lines.push(`created table ${t}`);
7142
- for (const c of result.schema?.added ?? []) lines.push(`added column ${c}`);
7143
- for (const i of result.schema?.indexed ?? []) lines.push(`indexed ${i}`);
7887
+ for (const t of result.schema.created) lines.push(`created table ${t}`);
7888
+ for (const c of result.schema.added) lines.push(`added column ${c}`);
7889
+ for (const i of result.schema.indexed) lines.push(`indexed ${i}`);
7144
7890
  const from = result.source.kind === "version" ? ` (v${result.source.n})` : "";
7145
7891
  if (result.status === "failed")
7146
7892
  throw new Error(
@@ -7150,7 +7896,7 @@ async function execute(ws, argv, stdin) {
7150
7896
  return out(lines.join("\n"), result);
7151
7897
  }
7152
7898
 
7153
- // `ez link` (docs/adr/0059): an address that opens the deployed app, or one of the caller's Previews (a
7899
+ // `ez link` (docs/adr/0203): an address that opens the deployed app, or one of the caller's Previews (a
7154
7900
  // bare --preview is the default name, as for `ez preview`), signed in as the caller's own Member identity.
7155
7901
  // The token travels in the fragment; the platform's handoff page spends it once.
7156
7902
  case "link": {
@@ -7227,8 +7973,7 @@ async function execute(ws, argv, stdin) {
7227
7973
  return out(`Edited ${path}.`, { path });
7228
7974
  }
7229
7975
 
7230
- case "delete":
7231
- case "rm": {
7976
+ case "delete": {
7232
7977
  const [path] = pos;
7233
7978
  if (!path) throw usage("ez delete <path>");
7234
7979
  if (path === CONTEXT_FILE)
@@ -7284,10 +8029,6 @@ async function execute(ws, argv, stdin) {
7284
8029
  const updated = await ws.updateSettings({ name });
7285
8030
  return out(`name: ${updated.name}`, updated);
7286
8031
  }
7287
- if (field === "signup")
7288
- throw new Error(
7289
- "There is no sign-up mode: the deployed apps are invite-only (ez user add <email>).",
7290
- );
7291
8032
  throw usage("ez config set name <value>");
7292
8033
  }
7293
8034
 
@@ -7308,10 +8049,6 @@ async function execute(ws, argv, stdin) {
7308
8049
  const updated = await ws.updateInstance({ name });
7309
8050
  return out(`name: ${updated.name}`, updated);
7310
8051
  }
7311
- if (field === "signup")
7312
- throw new Error(
7313
- "There is no sign-up mode: the deployed apps are invite-only (ez user add <email>).",
7314
- );
7315
8052
  throw usage("ez instance config set name <value>");
7316
8053
  }
7317
8054
 
@@ -7338,7 +8075,7 @@ async function execute(ws, argv, stdin) {
7338
8075
  { instance: inst.id, ...site },
7339
8076
  );
7340
8077
  }
7341
- if (sub === "archive" || sub === "rm") {
8078
+ if (sub === "archive") {
7342
8079
  const [, id] = pos;
7343
8080
  if (!id) throw usage("ez site archive <id>");
7344
8081
  const inst = await ws.instanceStatus();
@@ -7354,7 +8091,7 @@ async function execute(ws, argv, stdin) {
7354
8091
  const render = (a) => {
7355
8092
  if (!a.restricted)
7356
8093
  return out(
7357
- `open to every builder and member of the instance (run \`ez site access restrict\` to use allow-lists)${(a.groups ?? []).length ? `; restricting admits the groups ${a.groups.join(", ")}` : ""}`,
8094
+ `open to every builder and member of the instance (run \`ez site access restrict\` to use allow-lists)${a.groups.length ? `; restricting admits the groups ${a.groups.join(", ")}` : ""}`,
7358
8095
  a,
7359
8096
  );
7360
8097
  const lines = [
@@ -7367,14 +8104,14 @@ async function execute(ws, argv, stdin) {
7367
8104
  for (const p of a.members) lines.push(` ${p.email}${p.name ? ` ${p.name}` : ""}`);
7368
8105
  if (a.members.length === 0) lines.push(" (none)");
7369
8106
  lines.push("groups (their members, implied groups included):");
7370
- for (const g of a.groups ?? []) lines.push(` ${g}`);
7371
- if ((a.groups ?? []).length === 0) lines.push(" (none)");
8107
+ for (const g of a.groups) lines.push(` ${g}`);
8108
+ if (a.groups.length === 0) lines.push(" (none)");
7372
8109
  return out(lines.join("\n"), a);
7373
8110
  };
7374
8111
  if (verb === undefined) return render(await ws.siteAccess());
7375
8112
  if (verb === "restrict") return render(await ws.setRestricted(true));
7376
8113
  if (verb === "open") return render(await ws.setRestricted(false));
7377
- if ((verb === "add" || verb === "remove" || verb === "rm") && kind === "group" && who) {
8114
+ if ((verb === "add" || verb === "remove") && kind === "group" && who) {
7378
8115
  if (!GROUP_RE.test(who))
7379
8116
  throw new Error(
7380
8117
  `A group name is lowercase letters, digits and -, starting with a letter (at most 40): ${who}`,
@@ -7388,7 +8125,7 @@ async function execute(ws, argv, stdin) {
7388
8125
  );
7389
8126
  }
7390
8127
  if (
7391
- (verb === "add" || verb === "remove" || verb === "rm") &&
8128
+ (verb === "add" || verb === "remove") &&
7392
8129
  (kind === "builder" || kind === "user") &&
7393
8130
  who
7394
8131
  ) {
@@ -7410,7 +8147,7 @@ async function execute(ws, argv, stdin) {
7410
8147
  "ez site access [restrict|open|add builder|user <who>|add group <name>|remove builder|user <who>|remove group <name>]",
7411
8148
  );
7412
8149
  }
7413
- throw usage("ez site <ls|create|archive|rm|access> ...");
8150
+ throw usage("ez site <ls|create|archive|access> ...");
7414
8151
  }
7415
8152
 
7416
8153
  case "builders": {
@@ -7457,7 +8194,7 @@ async function execute(ws, argv, stdin) {
7457
8194
  await ws.setBuilderRole(target.id, role);
7458
8195
  return out(`${target.email} is now ${role}.`, { id: target.id, email: target.email, role });
7459
8196
  }
7460
- if (sub === "remove" || sub === "rm") {
8197
+ if (sub === "remove") {
7461
8198
  const [, who] = pos;
7462
8199
  if (!who) throw usage("ez builder remove <who>");
7463
8200
  const target = await resolvePerson(() => ws.listBuilders(), who, "builder");
@@ -7515,15 +8252,7 @@ async function execute(ws, argv, stdin) {
7515
8252
  row,
7516
8253
  );
7517
8254
  }
7518
- if (sub === "delete" || sub === "rm") {
7519
- if (!name) throw usage("ez asset delete <name> [--force]");
7520
- const rows = await ws.listAssets();
7521
- const hit = rows.find((r) => r.name === name);
7522
- if (!hit) throw new Error(`No such asset: ${name}`);
7523
- await ws.deleteAsset(hit.id, flags.has("--force"));
7524
- return out(`Deleted asset ${name}.`, { id: hit.id, name });
7525
- }
7526
- throw usage("ez asset add <name> <file> | ls | delete <name> [--force]");
8255
+ throw usage("ez asset add <name> <file> | ls");
7527
8256
  }
7528
8257
 
7529
8258
  case "users": {
@@ -7534,7 +8263,7 @@ async function execute(ws, argv, stdin) {
7534
8263
  .sort((a, b) => a.email.localeCompare(b.email))
7535
8264
  .map(
7536
8265
  (u) =>
7537
- `${u.email} ${u.status}${u.name ? ` ${u.name}` : ""}${u.groups?.length ? ` groups: ${u.groups.join(", ")}` : ""}${inviteSuffix(u)}`,
8266
+ `${u.email} ${u.status}${u.name ? ` ${u.name}` : ""}${u.groups.length ? ` groups: ${u.groups.join(", ")}` : ""}${inviteSuffix(u)}`,
7538
8267
  )
7539
8268
  .join("\n"),
7540
8269
  rows,
@@ -7569,7 +8298,7 @@ async function execute(ws, argv, stdin) {
7569
8298
  status: sub === "block" ? "blocked" : "active",
7570
8299
  });
7571
8300
  }
7572
- if (sub === "remove" || sub === "rm") {
8301
+ if (sub === "remove") {
7573
8302
  const [, who] = pos;
7574
8303
  if (!who) throw usage("ez user remove <who>");
7575
8304
  const target = await resolvePerson(() => ws.listUsers(), who, "member");
@@ -7581,14 +8310,14 @@ async function execute(ws, argv, stdin) {
7581
8310
  }
7582
8311
  if (sub === "group") {
7583
8312
  const [, verb, who, group] = pos;
7584
- if ((verb !== "add" && verb !== "remove" && verb !== "rm") || !who || !group)
8313
+ if ((verb !== "add" && verb !== "remove") || !who || !group)
7585
8314
  throw usage("ez user group add|remove <who> <group>");
7586
8315
  if (!GROUP_RE.test(group))
7587
8316
  throw new Error(
7588
8317
  `A group name is lowercase letters, digits and -, starting with a letter (at most 40): ${group}`,
7589
8318
  );
7590
8319
  const target = await resolvePerson(() => ws.listUsers(), who, "member");
7591
- const had = target.groups ?? [];
8320
+ const had = target.groups;
7592
8321
  const groups =
7593
8322
  verb === "add" ? [...new Set([...had, group])].sort() : had.filter((g) => g !== group);
7594
8323
  if (groups.length !== had.length) await ws.setUserGroups(target.id, groups);
@@ -7639,7 +8368,7 @@ async function execute(ws, argv, stdin) {
7639
8368
  }
7640
8369
 
7641
8370
  case "integration": {
7642
- // docs/adr/0092, 0138, 0140: every secret (a credential's value, a basic password, an OAuth client
8371
+ // docs/adr/0231, 0252: every secret (a credential's value, a basic password, an OAuth client
7643
8372
  // secret, a secret value) arrives on stdin (piped, or the CLI's hidden prompt), never as an argument,
7644
8373
  // and no result carries it.
7645
8374
  const credentialSyntax =
@@ -7793,7 +8522,7 @@ async function execute(ws, argv, stdin) {
7793
8522
  if (originError) throw new Error(originError);
7794
8523
  return { binding: { origin: new URL(origin).origin, credential }, preset };
7795
8524
  };
7796
- /** A preset's plain values, set on the binding after it (docs/adr/0138), the last answer kept. */
8525
+ /** A preset's plain values, set on the binding after it (docs/adr/0231), the last answer kept. */
7797
8526
  const presetValues = async (
7798
8527
  /** @type {import("./commands.d.mts").OAuthPreset | null} */ preset,
7799
8528
  /** @type {"production" | "preview"} */ bindingName,
@@ -7836,7 +8565,7 @@ async function execute(ws, argv, stdin) {
7836
8565
  const sites = given["--sites"];
7837
8566
  if (sites !== undefined) {
7838
8567
  const ids = sites === "all" ? "all" : sites.split(",").map((id) => id.trim());
7839
- // `global` names the Global Workspace's jobs (ADR 0136).
8568
+ // `global` names the Global Workspace's jobs (ADR 0230).
7840
8569
  if (
7841
8570
  ids !== "all" &&
7842
8571
  (!ids.length || ids.some((id) => id !== GLOBAL_ID && !isValidSiteId(id)))
@@ -7972,7 +8701,7 @@ async function execute(ws, argv, stdin) {
7972
8701
  }
7973
8702
 
7974
8703
  case "listener": {
7975
- // docs/adr/0092: a secret arrives on stdin (piped, or the CLI's hidden prompt), never as an argument.
8704
+ // docs/adr/0231: a secret arrives on stdin (piped, or the CLI's hidden prompt), never as an argument.
7976
8705
  const syntax =
7977
8706
  "ez listener list | secret <name> [--overlap <hours>] | secret <name> --remove | events <name> [--dead] | show <name> <event-id> | retry <name> <event-id>";
7978
8707
  const [sub, name, ...extra] = pos;
@@ -8085,7 +8814,7 @@ async function execute(ws, argv, stdin) {
8085
8814
  }
8086
8815
 
8087
8816
  case "key": {
8088
- // docs/adr/0119, docs/adr/0151: the Instance's API Keys, each shown once, by create, and never again.
8817
+ // docs/adr/0232: the Instance's API Keys, each shown once, by create, and never again.
8089
8818
  const syntax =
8090
8819
  "ez key list | create <name> [--groups <a,b>] [--sites <all | ids>] [--expires <days>] | revoke <name>";
8091
8820
  const VALUES = ["--groups", "--sites", "--expires"];
@@ -8178,7 +8907,7 @@ async function execute(ws, argv, stdin) {
8178
8907
  }
8179
8908
 
8180
8909
  case "email": {
8181
- // docs/adr/0149: the Emails the Instance's server code sent, newest first.
8910
+ // docs/adr/0234: the Emails the Instance's server code sent, newest first.
8182
8911
  const syntax =
8183
8912
  "ez email list [--site <id>] [--status <status>] [--since <YYYY-MM-DD>] [--limit <n>] | ez email show <id> [--html]";
8184
8913
  const [sub, ...rest] = args;
@@ -8241,7 +8970,7 @@ async function execute(ws, argv, stdin) {
8241
8970
  }
8242
8971
 
8243
8972
  case "support": {
8244
- // docs/adr/0080: a request to the Host's Developers, not to this Instance's Admins.
8973
+ // docs/adr/0208: a request to the Host's Developers, not to this Instance's Admins.
8245
8974
  const syntax =
8246
8975
  "ez support open <subject> [--body <text>] | ez support list | ez support show <id>";
8247
8976
  const [sub, ...rest] = args;
@@ -8332,11 +9061,11 @@ async function execute(ws, argv, stdin) {
8332
9061
  const lines = [];
8333
9062
  for (const t of tables) {
8334
9063
  lines.push(
8335
- `${t.name} ${plural(t.rows, "row")} ${t.history ? `the History of ${t.history} (read-only)` : `declared by ${t.sites.length ? t.sites.join(", ") : "no site"}`}`,
9064
+ `${t.name} ${plural(t.rows, "row")}${t.history ? ` the History of ${t.history} (read-only)` : ""}`,
8336
9065
  );
8337
9066
  for (const [c, d] of Object.entries(t.columns)) lines.push(` ${c} ${d}`);
8338
9067
  for (const cols of t.indexes) lines.push(` index (${cols.join(", ")})`);
8339
- for (const cols of t.unique ?? []) lines.push(` unique index (${cols.join(", ")})`);
9068
+ for (const cols of t.unique) lines.push(` unique index (${cols.join(", ")})`);
8340
9069
  }
8341
9070
  return out(lines.join("\n"), tables);
8342
9071
  }
@@ -8345,6 +9074,12 @@ async function execute(ws, argv, stdin) {
8345
9074
  return out(renderSchema(schema).trimEnd(), schema);
8346
9075
  }
8347
9076
  if (sub === "sql") {
9077
+ // A flag is never part of the statement: dropped silently, its value would be read as SQL.
9078
+ const stray = args.filter((a) => /^--[a-z]/.test(a) && a !== "--json");
9079
+ if (stray.length)
9080
+ throw usage(
9081
+ `ez db sql <statement> (or pipe the statement on stdin). It takes no ${stray[0]}${stray[0] === "--preview" ? ": the App Database is one, for the live app and every Preview alike" : " and no other flag: put the whole statement in quotes"}`,
9082
+ );
8348
9083
  const statement = (pos.slice(1).join(" ") || stdin || "").trim();
8349
9084
  if (!statement) throw usage("ez db sql <statement> (or pipe the statement on stdin)");
8350
9085
  const r = await ws.dbSql(statement);