ezship 0.1.15 → 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/README.md +60 -56
- package/access.d.mts +9 -5
- package/access.mjs +81 -41
- package/account.mjs +9 -8
- package/bindings.mjs +9 -27
- package/commands.d.mts +83 -67
- package/commands.mjs +1540 -547
- package/connections.d.mts +2 -3
- package/connections.mjs +10 -22
- package/cron.d.mts +1 -1
- package/cron.mjs +1 -1
- package/documents.d.mts +1 -1
- package/documents.mjs +1 -1
- package/editor-types.json.gz +0 -0
- package/editor.mjs +22 -56
- package/ez.mjs +50 -135
- package/package.json +7 -1
- package/paths.d.mts +22 -0
- package/paths.mjs +95 -0
- package/schema.d.mts +51 -47
- package/schema.mjs +390 -220
- package/session.d.mts +2 -3
- package/session.mjs +3 -5
- package/shape.d.mts +2 -2
- package/shape.mjs +1 -1
- package/signup.mjs +2 -2
- package/types.d.mts +73 -73
- package/update-check.mjs +1 -10
- package/workflow.d.mts +8 -2
- package/workflow.mjs +88 -21
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/
|
|
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/
|
|
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
|
|
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
|
|
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
|
|
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/
|
|
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
|
|
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/
|
|
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
|
|
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 (
|
|
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
|
|
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
|
|
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/
|
|
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 (
|
|
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
|
|
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
|
|
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/
|
|
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/
|
|
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/
|
|
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
|
|
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/
|
|
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/
|
|
618
|
-
* left off (docs/adr/
|
|
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/
|
|
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/
|
|
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/
|
|
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
|
|
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
|
|
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
|
|
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]:
|
|
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,
|
|
1085
|
-
|
|
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/
|
|
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: {
|
|
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/
|
|
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/
|
|
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
|
-
/**
|
|
2358
|
-
|
|
2359
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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/
|
|
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
|
|
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/
|
|
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/
|
|
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/
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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/
|
|
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
|
|
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/
|
|
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/
|
|
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/
|
|
2994
|
-
["page", "error", "a page.json problem (docs/adr/
|
|
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/
|
|
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/
|
|
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/
|
|
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,13 +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/
|
|
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
|
],
|
|
3504
|
+
[
|
|
3505
|
+
"@typescript-eslint/switch-exhaustiveness-check",
|
|
3506
|
+
"warning",
|
|
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)",
|
|
3508
|
+
"add a case for each value the message lists, or a default (an empty column's null need not be named)",
|
|
3509
|
+
],
|
|
3075
3510
|
[
|
|
3076
3511
|
"floating-write",
|
|
3077
3512
|
"warning",
|
|
3078
|
-
"a db write or server-function call whose promise nobody awaits (
|
|
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)",
|
|
3079
3514
|
"one click: onClick={() => run(() => db.update(...))}; a form: await it in useActionState(attempt(async () => ...), null)",
|
|
3080
3515
|
],
|
|
3081
3516
|
[
|
|
@@ -3096,23 +3531,11 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3096
3531
|
"a list key from the .map index",
|
|
3097
3532
|
"use the row's id as key: key={row.id}",
|
|
3098
3533
|
],
|
|
3099
|
-
[
|
|
3100
|
-
"ne-nullable",
|
|
3101
|
-
"warning",
|
|
3102
|
-
"{ col: { ne: x } } on a nullable column: it also drops rows where col is NULL",
|
|
3103
|
-
"{ nin: [x] } keeps the NULL rows; or ne on a column every row fills",
|
|
3104
|
-
],
|
|
3105
|
-
[
|
|
3106
|
-
"reduce-rows",
|
|
3107
|
-
"warning",
|
|
3108
|
-
"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",
|
|
3109
|
-
"use useLive.aggregate / useLive.count / db.aggregate",
|
|
3110
|
-
],
|
|
3111
3534
|
[
|
|
3112
3535
|
"filter-rows",
|
|
3113
3536
|
"warning",
|
|
3114
3537
|
"capped rows (100 by default) searched, filtered or paged in the page by what the user typed or picked",
|
|
3115
|
-
"put the condition in the query's where ({ col: {
|
|
3538
|
+
"put the condition in the query's where ({ col: { contains } }) and paging in limit/offset; show useLive.query's truncated",
|
|
3116
3539
|
],
|
|
3117
3540
|
[
|
|
3118
3541
|
"in-list-size",
|
|
@@ -3120,17 +3543,11 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3120
3543
|
"an in filter built from a query whose limit is above 400",
|
|
3121
3544
|
"split the list into chunks, or filter on a column instead",
|
|
3122
3545
|
],
|
|
3123
|
-
[
|
|
3124
|
-
"fn-op-budget",
|
|
3125
|
-
"warning",
|
|
3126
|
-
"a write inside a loop over unbounded data in a server function or job",
|
|
3127
|
-
"a call has 100 database operations: bound the loop, or write in chunks from several calls",
|
|
3128
|
-
],
|
|
3129
3546
|
[
|
|
3130
3547
|
"redundant-transaction",
|
|
3131
3548
|
"warning",
|
|
3132
3549
|
"a server function or job handler that returns db.transaction(...): every call is already one transaction",
|
|
3133
|
-
"write the callback's body in the handler, with db for tx (the
|
|
3550
|
+
"write the callback's body in the handler, with db for tx (the message shows it)",
|
|
3134
3551
|
],
|
|
3135
3552
|
[
|
|
3136
3553
|
"server-locale",
|
|
@@ -3147,43 +3564,49 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3147
3564
|
[
|
|
3148
3565
|
"schema-real-money",
|
|
3149
3566
|
"warning",
|
|
3150
|
-
"a REAL column named like money (price, amount, total, ...) (docs/adr/
|
|
3567
|
+
"a REAL column named like money (price, amount, total, ...) (docs/adr/0217)",
|
|
3151
3568
|
"declare <col> MONEY: whole cents, typed Cents; convert input with toCents()",
|
|
3152
3569
|
],
|
|
3153
3570
|
[
|
|
3154
3571
|
"table-cast",
|
|
3155
3572
|
"warning",
|
|
3156
|
-
'a cast in a Table argument (name as "orders") or to Query, Insert, Update, Where or Row (docs/adr/
|
|
3573
|
+
'a cast in a Table argument (name as "orders") or to Query, Insert, Update, Where or Row (docs/adr/0222)',
|
|
3157
3574
|
"a Table named at run time: db.table(name) or useLive.table(name, query); otherwise a literal name and no cast",
|
|
3158
3575
|
],
|
|
3159
3576
|
[
|
|
3160
3577
|
"query-sentinel",
|
|
3161
3578
|
"warning",
|
|
3162
|
-
'an empty id cast to match nothing: where: { id: "" as Id<...> } (docs/adr/
|
|
3579
|
+
'an empty id cast to match nothing: where: { id: "" as Id<...> } (docs/adr/0222)',
|
|
3163
3580
|
"skip the query: useLive(table, null), useLive.query(table, null), useLive.count(table, null)",
|
|
3164
3581
|
],
|
|
3165
3582
|
[
|
|
3166
3583
|
"error-text-match",
|
|
3167
3584
|
"warning",
|
|
3168
|
-
"an error's message tested for words: errorMessage(e).includes(...), /x/.test(e.message) (docs/adr/
|
|
3585
|
+
"an error's message tested for words: errorMessage(e).includes(...), /x/.test(e.message) (docs/adr/0222)",
|
|
3169
3586
|
'test the code: e instanceof WriteError && e.code === "unique"',
|
|
3170
3587
|
],
|
|
3171
3588
|
[
|
|
3172
3589
|
"enum-literal-copy",
|
|
3173
3590
|
"warning",
|
|
3174
|
-
"an array of strings that copies a CHECK list from global/db/schema.sql (docs/adr/
|
|
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)",
|
|
3175
3592
|
'read schema.column("<table>", "<col>")?.values, or let RecordForm and RecordList draw the choices',
|
|
3176
3593
|
],
|
|
3177
3594
|
[
|
|
3178
3595
|
"inline-style",
|
|
3179
3596
|
"warning",
|
|
3180
|
-
"a JSX style={{ ... }} whose every value is a literal (docs/adr/
|
|
3597
|
+
"a JSX style={{ ... }} whose every value is a literal (docs/adr/0215)",
|
|
3181
3598
|
"move these to a class in style.css and use className",
|
|
3182
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
|
+
],
|
|
3183
3606
|
]).map(([id, severity, summary, fix]) => Object.freeze({ id, severity, summary, fix })),
|
|
3184
3607
|
);
|
|
3185
3608
|
|
|
3186
|
-
/** The date before which no warning in `CHECK_RULES` becomes an error (docs/adr/
|
|
3609
|
+
/** The date before which no warning in `CHECK_RULES` becomes an error (docs/adr/0236). */
|
|
3187
3610
|
const WARNINGS_UNTIL = "2026-12-01";
|
|
3188
3611
|
|
|
3189
3612
|
/** @type {typeof import("./commands.d.mts").helpRules} */
|
|
@@ -3195,8 +3618,9 @@ export function helpRules() {
|
|
|
3195
3618
|
.map((r) => ` ${r.id.padEnd(width)} ${r.summary}\n ${" ".repeat(width)} fix: ${r.fix}`)
|
|
3196
3619
|
.join("\n");
|
|
3197
3620
|
return `The rules \`ez check\` runs (the same ones Push, Preview and Deploy run). Each problem names its rule id,
|
|
3198
|
-
a file and a line; \`ez check --json\` prints them as
|
|
3199
|
-
|
|
3621
|
+
a file and a line, and its message says what to write instead; \`ez check --json\` prints them as
|
|
3622
|
+
[{ file, line, column, rule, severity, message }]. No rule sends an edit to apply: make the change the
|
|
3623
|
+
message names. Errors fail the check; warnings never do.
|
|
3200
3624
|
Warnings become errors only in a platform release on or after ${WARNINGS_UNTIL}, announced here.
|
|
3201
3625
|
|
|
3202
3626
|
Errors:
|
|
@@ -3283,7 +3707,7 @@ export const RESERVED_INSTANCE_IDS = new Set([
|
|
|
3283
3707
|
"agents",
|
|
3284
3708
|
"i",
|
|
3285
3709
|
"s",
|
|
3286
|
-
// Names under the managed domain that are not Instances (ADR
|
|
3710
|
+
// Names under the managed domain that are not Instances (ADR 0245).
|
|
3287
3711
|
"www",
|
|
3288
3712
|
"chatgpt",
|
|
3289
3713
|
// The Developers' admin portal, a Worker beside the Studio (ezship-ops).
|
|
@@ -3296,49 +3720,29 @@ export function isValidInstanceId(id) {
|
|
|
3296
3720
|
}
|
|
3297
3721
|
|
|
3298
3722
|
/**
|
|
3299
|
-
* Site ids are permanent and public
|
|
3300
|
-
*
|
|
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).
|
|
3301
3725
|
* @type {typeof import("./commands.d.mts").SITE_ID_RE}
|
|
3302
3726
|
*/
|
|
3303
|
-
export const SITE_ID_RE = /^[
|
|
3304
|
-
/**
|
|
3305
|
-
* Path segments the Worker or studio use themselves; never a Site id.
|
|
3306
|
-
* @type {typeof import("./commands.d.mts").RESERVED_SITE_IDS}
|
|
3307
|
-
*/
|
|
3308
|
-
export const RESERVED_SITE_IDS = new Set([
|
|
3309
|
-
"app",
|
|
3310
|
-
"s",
|
|
3311
|
-
"i",
|
|
3312
|
-
"api",
|
|
3313
|
-
"auth",
|
|
3314
|
-
"studio",
|
|
3315
|
-
"static",
|
|
3316
|
-
"assets",
|
|
3317
|
-
"cli",
|
|
3318
|
-
"preview",
|
|
3319
|
-
"agents",
|
|
3320
|
-
"settings",
|
|
3321
|
-
"global", // the Global Workspace's target id
|
|
3322
|
-
]);
|
|
3323
|
-
|
|
3727
|
+
export const SITE_ID_RE = /^[0-9a-hjkmnp-tv-z]{12}$/;
|
|
3324
3728
|
/** @type {typeof import("./commands.d.mts").isValidSiteId} */
|
|
3325
3729
|
export function isValidSiteId(id) {
|
|
3326
|
-
return typeof id === "string" && SITE_ID_RE.test(id)
|
|
3730
|
+
return typeof id === "string" && SITE_ID_RE.test(id);
|
|
3327
3731
|
}
|
|
3328
3732
|
|
|
3329
3733
|
/**
|
|
3330
|
-
* An Instance folder on disk holds `global/` and `sites/<folder>/`, one per Site (ADR
|
|
3734
|
+
* An Instance folder on disk holds `global/` and `sites/<folder>/`, one per Site (ADR 0205).
|
|
3331
3735
|
* @type {typeof import("./commands.d.mts").SITES_FOLDER}
|
|
3332
3736
|
*/
|
|
3333
3737
|
export const SITES_FOLDER = "sites";
|
|
3334
3738
|
/**
|
|
3335
|
-
* The folder names an Instance folder keeps for itself; no Site name may slugify to one (ADR
|
|
3739
|
+
* The folder names an Instance folder keeps for itself; no Site name may slugify to one (ADR 0205).
|
|
3336
3740
|
* @type {typeof import("./commands.d.mts").RESERVED_FOLDER_NAMES}
|
|
3337
3741
|
*/
|
|
3338
3742
|
export const RESERVED_FOLDER_NAMES = new Set([GLOBAL_ID, SITES_FOLDER]);
|
|
3339
3743
|
|
|
3340
3744
|
/**
|
|
3341
|
-
* A display name as a folder name: lowercase, hyphen-separated, never empty (ADR
|
|
3745
|
+
* A display name as a folder name: lowercase, hyphen-separated, never empty (ADR 0205).
|
|
3342
3746
|
* @type {typeof import("./commands.d.mts").siteFolderName}
|
|
3343
3747
|
*/
|
|
3344
3748
|
export function siteFolderName(name) {
|
|
@@ -3359,7 +3763,7 @@ export function siteNameError(name) {
|
|
|
3359
3763
|
return null;
|
|
3360
3764
|
}
|
|
3361
3765
|
|
|
3362
|
-
// ---- Previews (docs/adr/
|
|
3766
|
+
// ---- Previews (docs/adr/0212) ---------------------------------------------------------------------------
|
|
3363
3767
|
|
|
3364
3768
|
/**
|
|
3365
3769
|
* The path segment under a Site's prefix that serves a Preview: <prefix>/~preview/<id>/.
|
|
@@ -3379,13 +3783,13 @@ export const MAX_PREVIEWS_PER_BUILDER = 10;
|
|
|
3379
3783
|
*/
|
|
3380
3784
|
export const PREVIEW_IDLE_MS = 7 * 24 * 60 * 60 * 1000;
|
|
3381
3785
|
/**
|
|
3382
|
-
* One-time app links (docs/adr/
|
|
3786
|
+
* One-time app links (docs/adr/0203): `ez link` opens the app or a Preview signed in as the caller's own
|
|
3383
3787
|
* Member identity; the link works once, within this long.
|
|
3384
3788
|
* @type {typeof import("./commands.d.mts").APP_LINK_TTL_MS}
|
|
3385
3789
|
*/
|
|
3386
3790
|
export const APP_LINK_TTL_MS = 5 * 60 * 1000;
|
|
3387
3791
|
/**
|
|
3388
|
-
* Support Requests (docs/adr/
|
|
3792
|
+
* Support Requests (docs/adr/0208): a subject and a body for the Host's Developers, a few a day per Builder.
|
|
3389
3793
|
* @type {typeof import("./commands.d.mts").SUPPORT_SUBJECT_MAX}
|
|
3390
3794
|
*/
|
|
3391
3795
|
export const SUPPORT_SUBJECT_MAX = 200;
|
|
@@ -3394,7 +3798,7 @@ export const SUPPORT_BODY_MAX = 20_000;
|
|
|
3394
3798
|
/** @type {typeof import("./commands.d.mts").SUPPORT_REQUESTS_PER_DAY} */
|
|
3395
3799
|
export const SUPPORT_REQUESTS_PER_DAY = 10;
|
|
3396
3800
|
|
|
3397
|
-
// ---- Emails (docs/adr/
|
|
3801
|
+
// ---- Emails (docs/adr/0234) ---------------------------------------------------------------------------
|
|
3398
3802
|
|
|
3399
3803
|
/**
|
|
3400
3804
|
* What `email.send` takes and how much the Host sends: Emails per invocation, the subject's and the body's
|
|
@@ -3422,7 +3826,7 @@ export const EMAIL_STATUSES = Object.freeze([
|
|
|
3422
3826
|
"dropped",
|
|
3423
3827
|
]);
|
|
3424
3828
|
|
|
3425
|
-
// ---- Integrations (docs/adr/
|
|
3829
|
+
// ---- Integrations (docs/adr/0231) -----------------------------------------------------------------
|
|
3426
3830
|
//
|
|
3427
3831
|
// An Instance's named external services, set by Admins, called by server code with a credential it never
|
|
3428
3832
|
// sees. The names, kinds, credential types and limits are data here, for the CLI, the Pipeline and the Host.
|
|
@@ -3452,7 +3856,7 @@ export const INTEGRATION_LIMITS = Object.freeze({
|
|
|
3452
3856
|
inFlightPerInstance: 4,
|
|
3453
3857
|
perSecond: 10,
|
|
3454
3858
|
burst: 60,
|
|
3455
|
-
// ADR
|
|
3859
|
+
// ADR 0231: a binding's values, the headers it may add in all, and the shortest secret the Host looks
|
|
3456
3860
|
// for in an answer (and shows a hint of).
|
|
3457
3861
|
valuesPerBinding: 20,
|
|
3458
3862
|
addedHeaderBytes: 8192,
|
|
@@ -3532,7 +3936,7 @@ export function basicUserError(user) {
|
|
|
3532
3936
|
return null;
|
|
3533
3937
|
}
|
|
3534
3938
|
|
|
3535
|
-
// ---- OAuth (docs/adr/
|
|
3939
|
+
// ---- OAuth (docs/adr/0252, a draft) --------------------------------------------------------------------
|
|
3536
3940
|
//
|
|
3537
3941
|
// An OAuth credential is stored and listed, and every call on it is refused `grant` ("not connected"),
|
|
3538
3942
|
// until the draft's flows (connect, the callback, refresh) are built. Presets are provider facts, data here.
|
|
@@ -3546,10 +3950,10 @@ export const OAUTH_CLIENT_AUTH = Object.freeze(/** @type {const} */ (["basic", "
|
|
|
3546
3950
|
/** What `ez integration` says of an OAuth credential while the draft's flows are not built. */
|
|
3547
3951
|
/** @type {typeof import("./commands.d.mts").OAUTH_NOT_BUILT} */
|
|
3548
3952
|
export const OAUTH_NOT_BUILT =
|
|
3549
|
-
"OAuth flows are not implemented yet (ADR
|
|
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.";
|
|
3550
3954
|
|
|
3551
3955
|
/**
|
|
3552
|
-
* Providers whose OAuth facts are certain (docs/adr/
|
|
3956
|
+
* Providers whose OAuth facts are certain (docs/adr/0231): the API's origin and its sandbox's, the URLs, the
|
|
3553
3957
|
* default scopes, the client's authentication, and the plain values every request needs.
|
|
3554
3958
|
* @type {typeof import("./commands.d.mts").OAUTH_PRESETS}
|
|
3555
3959
|
*/
|
|
@@ -3636,9 +4040,9 @@ export function oauthCredentialError(c, allowHttp = false) {
|
|
|
3636
4040
|
return null;
|
|
3637
4041
|
}
|
|
3638
4042
|
|
|
3639
|
-
// ---- invites (docs/adr/
|
|
4043
|
+
// ---- invites (docs/adr/0202) ----------------------------------------------------------------------------
|
|
3640
4044
|
//
|
|
3641
|
-
// An invite is a pre-created identity row (docs/adr/
|
|
4045
|
+
// An invite is a pre-created identity row (docs/adr/0202) that the person claims by signing in. It is claimable
|
|
3642
4046
|
// for INVITE_TTL_MS after the last invite from any Instance; re-adding the person restarts the window.
|
|
3643
4047
|
|
|
3644
4048
|
/** @type {typeof import("./commands.d.mts").INVITE_TTL_MS} */
|
|
@@ -3745,7 +4149,7 @@ export const ROUTES = Object.freeze({
|
|
|
3745
4149
|
instanceStatus: { method: "GET", path: INSTANCE },
|
|
3746
4150
|
updateInstance: { method: "PATCH", path: INSTANCE, args: (patch) => body(patch) },
|
|
3747
4151
|
listAudit: { method: "GET", path: `${INSTANCE}/audit`, args: (filter) => ({ query: filter }) },
|
|
3748
|
-
// the App Database is the Instance's (docs/adr/
|
|
4152
|
+
// the App Database is the Instance's (docs/adr/0217): no Site in the path
|
|
3749
4153
|
dbSchema: { method: "GET", path: `${INSTANCE}/db/schema` },
|
|
3750
4154
|
dbTables: { method: "GET", path: `${INSTANCE}/db/tables` },
|
|
3751
4155
|
dbSql: { method: "POST", path: `${INSTANCE}/db/sql`, args: (statement) => body({ statement }) },
|
|
@@ -3755,15 +4159,15 @@ export const ROUTES = Object.freeze({
|
|
|
3755
4159
|
args: (table, query) => ({ params: { table }, body: query }),
|
|
3756
4160
|
},
|
|
3757
4161
|
dbActors: { method: "POST", path: `${INSTANCE}/db/actors`, args: (query) => body(query) },
|
|
3758
|
-
// A read-only query as one Member sees the rows (docs/adr/
|
|
4162
|
+
// A read-only query as one Member sees the rows (docs/adr/0225), for testing access rules.
|
|
3759
4163
|
dbQueryAs: {
|
|
3760
4164
|
method: "POST",
|
|
3761
4165
|
path: `${INSTANCE}/db/query/:table`,
|
|
3762
4166
|
args: (table, as, query) => ({ params: { table }, body: { as, query } }),
|
|
3763
4167
|
},
|
|
3764
|
-
// the one write to a History (docs/adr/
|
|
4168
|
+
// the one write to a History (docs/adr/0218); Admins only, and no Site code reaches it
|
|
3765
4169
|
dbRedact: { method: "POST", path: `${INSTANCE}/db/redact`, args: (input) => body(input) },
|
|
3766
|
-
// App Attachments (docs/adr/
|
|
4170
|
+
// App Attachments (docs/adr/0221); the bytes go to the ticket's URL (`.../db/attachments/:id/bytes`), outside this table
|
|
3767
4171
|
requestAttachment: {
|
|
3768
4172
|
method: "POST",
|
|
3769
4173
|
path: `${INSTANCE}/db/attachments`,
|
|
@@ -3790,24 +4194,24 @@ export const ROUTES = Object.freeze({
|
|
|
3790
4194
|
args: (id, status) => ({ params: { id }, body: { status } }),
|
|
3791
4195
|
},
|
|
3792
4196
|
removeUser: { method: "DELETE", path: `${INSTANCE}/users/:id`, args: byId },
|
|
3793
|
-
// Member groups on the roster (docs/adr/
|
|
4197
|
+
// Member groups on the roster (docs/adr/0225): the whole list at once.
|
|
3794
4198
|
setUserGroups: {
|
|
3795
4199
|
method: "PUT",
|
|
3796
4200
|
path: `${INSTANCE}/users/:id/groups`,
|
|
3797
4201
|
args: (id, groups) => ({ params: { id }, body: { groups } }),
|
|
3798
4202
|
},
|
|
3799
|
-
// Support Requests to the Host's Developers (docs/adr/
|
|
4203
|
+
// Support Requests to the Host's Developers (docs/adr/0208)
|
|
3800
4204
|
openSupportRequest: { method: "POST", path: `${INSTANCE}/support`, args: (input) => body(input) },
|
|
3801
4205
|
listSupportRequests: { method: "GET", path: `${INSTANCE}/support` },
|
|
3802
4206
|
supportRequest: { method: "GET", path: `${INSTANCE}/support/:id`, args: byId },
|
|
3803
|
-
// Emails server code sent (docs/adr/
|
|
4207
|
+
// Emails server code sent (docs/adr/0234): every Builder reads them; a Limited Builder only their Sites'.
|
|
3804
4208
|
listEmails: {
|
|
3805
4209
|
method: "GET",
|
|
3806
4210
|
path: `${INSTANCE}/emails`,
|
|
3807
4211
|
args: (filter) => ({ query: { ...filter } }),
|
|
3808
4212
|
},
|
|
3809
4213
|
emailInfo: { method: "GET", path: `${INSTANCE}/emails/:id`, args: byId },
|
|
3810
|
-
// Integrations (docs/adr/
|
|
4214
|
+
// Integrations (docs/adr/0231): Admins set them; every Builder lists them and their calls.
|
|
3811
4215
|
listIntegrations: { method: "GET", path: `${INSTANCE}/integrations` },
|
|
3812
4216
|
setIntegration: {
|
|
3813
4217
|
method: "PUT",
|
|
@@ -3819,7 +4223,7 @@ export const ROUTES = Object.freeze({
|
|
|
3819
4223
|
path: `${INSTANCE}/integrations/:name/preview`,
|
|
3820
4224
|
args: (name, input) => ({ params: { name }, body: input }),
|
|
3821
4225
|
},
|
|
3822
|
-
// ADR
|
|
4226
|
+
// ADR 0231: one header or parameter the Host adds to a binding's every request.
|
|
3823
4227
|
setIntegrationValue: {
|
|
3824
4228
|
method: "PUT",
|
|
3825
4229
|
path: `${INSTANCE}/integrations/:name/values`,
|
|
@@ -3848,7 +4252,7 @@ export const ROUTES = Object.freeze({
|
|
|
3848
4252
|
path: `${INSTANCE}/integrations/:name/test`,
|
|
3849
4253
|
args: (name, input) => ({ params: { name }, body: input }),
|
|
3850
4254
|
},
|
|
3851
|
-
// the Instance's schedules (
|
|
4255
|
+
// the Instance's schedules (ADR 0230), from the pushed global/schedules.json; ADR 0230: a pause is
|
|
3852
4256
|
// the Host's, on the active schedule, and a resume never catches up
|
|
3853
4257
|
listSchedules: { method: "GET", path: `${INSTANCE}/schedules` },
|
|
3854
4258
|
listScheduleRuns: {
|
|
@@ -3871,15 +4275,10 @@ export const ROUTES = Object.freeze({
|
|
|
3871
4275
|
path: `${INSTANCE}/schedules/:name/resume`,
|
|
3872
4276
|
args: (name) => ({ params: { name } }),
|
|
3873
4277
|
},
|
|
3874
|
-
// the Instance's assets (docs/adr/
|
|
4278
|
+
// the Instance's assets (docs/adr/0213); the bytes go to the ticket's URL, outside this table
|
|
3875
4279
|
listAssets: { method: "GET", path: `${INSTANCE}/assets` },
|
|
3876
4280
|
requestUpload: { method: "POST", path: `${INSTANCE}/assets`, args: (input) => body(input) },
|
|
3877
4281
|
finalizeUpload: { method: "POST", path: `${INSTANCE}/assets/:id/ready`, args: byId },
|
|
3878
|
-
deleteAsset: {
|
|
3879
|
-
method: "DELETE",
|
|
3880
|
-
path: `${INSTANCE}/assets/:id`,
|
|
3881
|
-
args: (id, force) => ({ params: { id }, query: force ? { force: 1 } : {} }),
|
|
3882
|
-
},
|
|
3883
4282
|
// the Site
|
|
3884
4283
|
remoteStatus: { method: "GET", path: `${SITE}/workspace` },
|
|
3885
4284
|
updateSettings: { method: "PATCH", path: `${SITE}/workspace`, args: (patch) => body(patch) },
|
|
@@ -3888,12 +4287,12 @@ export const ROUTES = Object.freeze({
|
|
|
3888
4287
|
pushAll: {
|
|
3889
4288
|
method: "POST",
|
|
3890
4289
|
path: `${SITE}/push`,
|
|
3891
|
-
// `options`: the message (docs/adr/
|
|
3892
|
-
// (docs/adr/
|
|
4290
|
+
// `options`: the message (docs/adr/0211) and a Global push's dryRun, acknowledgeExposure and force
|
|
4291
|
+
// (docs/adr/0224, 0225).
|
|
3893
4292
|
args: (files, prune, deleted = [], options = {}) => body({ files, prune, deleted, ...options }),
|
|
3894
4293
|
},
|
|
3895
4294
|
deploy: { method: "POST", path: `${SITE}/deploy` },
|
|
3896
|
-
// Listeners (docs/adr/
|
|
4295
|
+
// Listeners (docs/adr/0231): any Builder of the Site; a secret travels once, in a PUT's body.
|
|
3897
4296
|
listListeners: { method: "GET", path: `${SITE}/listeners` },
|
|
3898
4297
|
setListenerSecret: {
|
|
3899
4298
|
method: "PUT",
|
|
@@ -3920,7 +4319,7 @@ export const ROUTES = Object.freeze({
|
|
|
3920
4319
|
path: `${SITE}/listeners/:name/events/:id/retry`,
|
|
3921
4320
|
args: (name, id) => ({ params: { name, id } }),
|
|
3922
4321
|
},
|
|
3923
|
-
// API Keys (docs/adr/
|
|
4322
|
+
// API Keys (docs/adr/0232): the Instance's; Admins create and revoke, every Builder lists.
|
|
3924
4323
|
listApiKeys: { method: "GET", path: `${INSTANCE}/keys` },
|
|
3925
4324
|
createApiKey: { method: "POST", path: `${INSTANCE}/keys`, args: (input) => body(input) },
|
|
3926
4325
|
revokeApiKey: {
|
|
@@ -3939,7 +4338,7 @@ export const ROUTES = Object.freeze({
|
|
|
3939
4338
|
args: (files, global) => body({ files, ...(global ? { global } : {}) }),
|
|
3940
4339
|
},
|
|
3941
4340
|
format: { method: "POST", path: `${SITE}/format`, args: (files) => body({ files }) },
|
|
3942
|
-
// Documents (docs/adr/
|
|
4341
|
+
// Documents (docs/adr/0233): in a Site a queued Render; in the Global Workspace (`files`) an immediate one
|
|
3943
4342
|
renderDocument: {
|
|
3944
4343
|
method: "POST",
|
|
3945
4344
|
path: `${SITE}/renders`,
|
|
@@ -3970,7 +4369,7 @@ export const ROUTES = Object.freeze({
|
|
|
3970
4369
|
denyBuilder: { method: "DELETE", path: `${SITE}/access/builders/:id`, args: byId },
|
|
3971
4370
|
allowUser: { method: "POST", path: `${SITE}/access/members`, args: (id) => body({ id }) },
|
|
3972
4371
|
denyUser: { method: "DELETE", path: `${SITE}/access/members/:id`, args: byId },
|
|
3973
|
-
// A Restricted Site's groups (docs/adr/
|
|
4372
|
+
// A Restricted Site's groups (docs/adr/0225): their Members may open it too.
|
|
3974
4373
|
allowGroup: {
|
|
3975
4374
|
method: "POST",
|
|
3976
4375
|
path: `${SITE}/access/groups`,
|
|
@@ -4083,7 +4482,7 @@ export const AUDIT_KINDS = Object.freeze([
|
|
|
4083
4482
|
"site.archive",
|
|
4084
4483
|
"site.config",
|
|
4085
4484
|
"site.access",
|
|
4086
|
-
"builder.password-setup", // Historical (docs/adr/
|
|
4485
|
+
"builder.password-setup", // Historical (docs/adr/0202 retired setup links); events remain readable.
|
|
4087
4486
|
"member.password-setup",
|
|
4088
4487
|
"builder.add",
|
|
4089
4488
|
"builder.role",
|
|
@@ -4093,28 +4492,28 @@ export const AUDIT_KINDS = Object.freeze([
|
|
|
4093
4492
|
"member.unblock",
|
|
4094
4493
|
"member.remove",
|
|
4095
4494
|
"member.session",
|
|
4096
|
-
"member.groups", // a Member's roster groups changed (docs/adr/
|
|
4495
|
+
"member.groups", // a Member's roster groups changed (docs/adr/0225)
|
|
4097
4496
|
"files.push",
|
|
4098
4497
|
"deploy",
|
|
4099
4498
|
"preview.schema",
|
|
4100
4499
|
"asset.add",
|
|
4101
4500
|
"asset.remove",
|
|
4102
4501
|
"db.sql", // a write through `ez db sql`; details keep the capped statement text
|
|
4103
|
-
"db.attach", // `ez db attach`: an attachment bound to a row (docs/adr/
|
|
4104
|
-
"db.query-as", // `ez db query --as`: a Builder read rows as one Member sees them (docs/adr/
|
|
4105
|
-
"schedule.run", // `ez schedule run`: a schedule's job run now (docs/adr/
|
|
4106
|
-
"schedule.pause", // `ez schedule pause`: a schedule's due times stopped (docs/adr/
|
|
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)
|
|
4107
4506
|
"schedule.resume", // `ez schedule resume`: started again from now
|
|
4108
|
-
"integration.set", // an Integration's production binding, Sites or timeout (docs/adr/
|
|
4507
|
+
"integration.set", // an Integration's production binding, Sites or timeout (docs/adr/0231)
|
|
4109
4508
|
"integration.preview", // an Integration's Preview binding
|
|
4110
|
-
"integration.value", // a header or parameter a binding adds (docs/adr/
|
|
4509
|
+
"integration.value", // a header or parameter a binding adds (docs/adr/0231); a secret one never in details
|
|
4111
4510
|
"integration.remove",
|
|
4112
4511
|
"integration.test", // `ez integration test`: one request, its path omitted
|
|
4113
|
-
"listener.secret", // a Listener's verification secret set or removed (docs/adr/
|
|
4512
|
+
"listener.secret", // a Listener's verification secret set or removed (docs/adr/0231)
|
|
4114
4513
|
"listener.retry", // a dead event put back to pending
|
|
4115
|
-
"api.key", // an API Key created or revoked (docs/adr/
|
|
4116
|
-
"document.render", // `ez document render` or `ez global document render` (docs/adr/
|
|
4117
|
-
"db.redact", // `ez db redact`: columns blanked in rows and their History (docs/adr/
|
|
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
|
|
4118
4517
|
]);
|
|
4119
4518
|
|
|
4120
4519
|
// ---- change tracking -----------------------------------------------------------------------------------
|
|
@@ -4163,7 +4562,7 @@ export const countChanges = (c) => c.added.length + c.modified.length + c.delete
|
|
|
4163
4562
|
// Tags say what kind of statement a line is: [check] ez check (and push/preview/deploy) refuses it with a rule
|
|
4164
4563
|
// id, [runtime] the Host refuses or limits it when it runs, [advice] a default to follow that nothing checks.
|
|
4165
4564
|
|
|
4166
|
-
/** `ez help` and `ez help lifecycle`: what each command reads, changes and shows (docs/adr/
|
|
4565
|
+
/** `ez help` and `ez help lifecycle`: what each command reads, changes and shows (docs/adr/0212, 0210, 0217, 0224). */
|
|
4167
4566
|
const LIFECYCLE = `The lifecycle: what each command builds from, changes and shows. There are six states: your Site files
|
|
4168
4567
|
(this Working Copy), your Global files (global/ beside it), the pushed Site and Global Versions (the Shared
|
|
4169
4568
|
Files every Builder pulls), the deployed Site (a build Members use), the published schema (global
|
|
@@ -4230,6 +4629,11 @@ const SITE_FILES = `${aligned([
|
|
|
4230
4629
|
"custom hooks, one per file, `export default function use<Name>()`, no markup",
|
|
4231
4630
|
"ez help frame",
|
|
4232
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
|
+
],
|
|
4233
4637
|
[
|
|
4234
4638
|
`${FUNCTIONS_DIR}<name>.ts`,
|
|
4235
4639
|
"server functions: default-export serverFunction(inputSchema, handler)",
|
|
@@ -4348,7 +4752,7 @@ files. What a React developer reaches for, and what to write here:
|
|
|
4348
4752
|
${aligned([
|
|
4349
4753
|
[
|
|
4350
4754
|
"load data, live",
|
|
4351
|
-
'useLive("orders", { where: { status: "open" } }); useLive.count
|
|
4755
|
+
'useLive.query("orders", { where: { status: "open" } }) -> { rows, truncated, loading }; useLive.count',
|
|
4352
4756
|
"data",
|
|
4353
4757
|
],
|
|
4354
4758
|
[
|
|
@@ -4376,6 +4780,11 @@ ${aligned([
|
|
|
4376
4780
|
"functions/<name>.ts: serverFunction(z.object(...), handler)",
|
|
4377
4781
|
"functions",
|
|
4378
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
|
+
],
|
|
4379
4788
|
[
|
|
4380
4789
|
"logic pages and functions share",
|
|
4381
4790
|
"global/lib/<name>.ts: named exports, the db passed in",
|
|
@@ -4394,6 +4803,7 @@ ${aligned([
|
|
|
4394
4803
|
["a viewer's preference across pages", 'useSession("activeCompanyId"), Session State', "frame"],
|
|
4395
4804
|
["state a link carries", 'useSearchParam("state"); <Link to="/orders?state=open">', "frame"],
|
|
4396
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"],
|
|
4397
4807
|
["routes", "pages/<route>.tsx; <Link to>, useNavigate(), useParams()", "files"],
|
|
4398
4808
|
[
|
|
4399
4809
|
"who sees which rows",
|
|
@@ -4405,7 +4815,7 @@ ${aligned([
|
|
|
4405
4815
|
"useAuth() -> { user, membership, me, groups }; sign-in is the platform's",
|
|
4406
4816
|
"access",
|
|
4407
4817
|
],
|
|
4408
|
-
["styling", "className and style.css
|
|
4818
|
+
["styling", "className, the Theme's tokens and classes; style.css adds a Site's own", "files"],
|
|
4409
4819
|
[
|
|
4410
4820
|
"cron, webhooks, desktop files, PDFs",
|
|
4411
4821
|
"jobs/, listeners/, local/, global/documents/",
|
|
@@ -4413,12 +4823,13 @@ ${aligned([
|
|
|
4413
4823
|
],
|
|
4414
4824
|
])}
|
|
4415
4825
|
Restrictions, each with its replacement:
|
|
4416
|
-
[check] From react only useState, useActionState, useTransition, startTransition, useOptimistic
|
|
4417
|
-
no useEffect, useRef,
|
|
4418
|
-
useCall, the React Compiler memoizes,
|
|
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)
|
|
4419
4830
|
[check] No fetch, window, document, timers or storage: db and useLive for data, Integrations for other
|
|
4420
|
-
services, useSession for preferences, useInterval and useDebounced for time. confirm(), alert()
|
|
4421
|
-
and
|
|
4831
|
+
services, useSession for preferences, useInterval and useDebounced for time. confirm(), alert(),
|
|
4832
|
+
prompt() and print() are allowed in event handlers. (no-restricted-globals)
|
|
4422
4833
|
[check] No packages but recharts, no URLs, dynamic import() or file extensions in imports; only what
|
|
4423
4834
|
\`ez help files\` lists. Pages are never imported. (import)
|
|
4424
4835
|
[check] No classes; constants.ts holds plain values only. (class, constant-shape)
|
|
@@ -4428,11 +4839,18 @@ Restrictions, each with its replacement:
|
|
|
4428
4839
|
[check] Name an Integration with a string literal. (integration-literal)
|
|
4429
4840
|
[runtime] Row queries return 100 rows by default and 1000 at most: totals come from useLive.count and
|
|
4430
4841
|
aggregates, never from reducing rows.
|
|
4431
|
-
[runtime] A server function or job call:
|
|
4432
|
-
no network but Integrations, no locales (no Intl).
|
|
4842
|
+
[runtime] A server function or job call: 10 seconds, 5 seconds holding the database (ez help functions), 32 MB
|
|
4843
|
+
heap, 1,000 database operations, 256 KB in and out, no network but Integrations, no locales (no Intl).
|
|
4844
|
+
One transaction per call, which runs as if it were alone; each db call from a page is its own.
|
|
4433
4845
|
[runtime] Preview data is production data: every Preview write is real.
|
|
4434
4846
|
[advice] Await every write; key list items by the row's id; use errorMessage(e), never \`e as Error\`;
|
|
4435
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)
|
|
4436
4854
|
[advice] One Site is one audience and a few pages: when a request needs another audience or grows past a
|
|
4437
4855
|
few pages, say it belongs in another Site. A request outside this shape is a limit to report to
|
|
4438
4856
|
the user, not a workaround to find.
|
|
@@ -4453,7 +4871,7 @@ How to work
|
|
|
4453
4871
|
a component before the page that imports it, a function before its caller. \`ez help recipes\` has
|
|
4454
4872
|
complete examples of the common pieces.
|
|
4455
4873
|
5. \`ez check\` after each change and fix what it reports, errors and warnings, before you say a change is
|
|
4456
|
-
done; \`ez check --json\` gives each problem as data
|
|
4874
|
+
done; \`ez check --json\` gives each problem as data, its message naming the change to make.
|
|
4457
4875
|
\`ez format\` lays out the code in ezship's one style; run it before you push.
|
|
4458
4876
|
6. \`ez preview\` (or \`ez dev\`, which keeps it current) and give the user \`ez link --preview <name>\`;
|
|
4459
4877
|
a successful preview is also a check. Its data is the live data.
|
|
@@ -4469,6 +4887,24 @@ for a problem in the code you are writing. Keep replies brief.
|
|
|
4469
4887
|
|
|
4470
4888
|
${LIFECYCLE}`;
|
|
4471
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
|
+
|
|
4472
4908
|
/** `ez help files`: the shapes and what each kind of file may import, from the contract's own messages. */
|
|
4473
4909
|
const FILES_TOPIC = `Files and imports. The Site:
|
|
4474
4910
|
${SITE_FILES}
|
|
@@ -4476,12 +4912,15 @@ The Global Workspace:
|
|
|
4476
4912
|
${GLOBAL_FILES}
|
|
4477
4913
|
[check] What each file may import (the same sentences ez check prints):
|
|
4478
4914
|
Pages, components, hooks and App.tsx: ${IMPORT_SHAPE}
|
|
4479
|
-
From react: useState, useActionState, useTransition, startTransition, useOptimistic
|
|
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
|
|
4480
4917
|
imports \`import type { Provided } from "../App"\` for App.tsx's values (ez help frame).
|
|
4481
4918
|
Server functions (functions/): @ezship/react/server (serverFunction, z and types), constants, sibling
|
|
4482
|
-
functions, global/constants, global/lib/<name>, global/documents/<Name> and type-only
|
|
4483
|
-
|
|
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
|
|
4484
4922
|
global/db/types and sibling functions (not global/documents); nothing imports a listener.
|
|
4923
|
+
Site lib (lib/): ${SITE_LIB_IMPORT_SHAPE}
|
|
4485
4924
|
Global jobs (global/jobs/): @ezship/react/server, global/lib/<name>, global/constants and type-only
|
|
4486
4925
|
global/db/types; nothing imports a job.
|
|
4487
4926
|
Local functions (local/): @ezship/react/local, node:* built-ins, constants, sibling local functions and
|
|
@@ -4498,23 +4937,270 @@ Routes: the page file name is the route. index.tsx is /, orders.tsx is /orders,
|
|
|
4498
4937
|
/orders/:id (useParams().id), orders.new.tsx is /orders/new. <Link to="/orders/42">, <Link to="/orders"
|
|
4499
4938
|
site="kitchen"> (another Site of the Instance), useNavigate()(path), useSites() -> [{ id, name, url, current }].
|
|
4500
4939
|
A Link to the open route has aria-current="page", to its section aria-current="true": style a[aria-current].
|
|
4501
|
-
Styling: className and the Site's style.css
|
|
4502
|
-
|
|
4503
|
-
|
|
4504
|
-
|
|
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
|
|
4956
|
+
* `help.test.ts` checks `before + code + after` as the file `path`, with no warnings, against the starter
|
|
4957
|
+
* Global Workspace and `HELP_SNIPPET_SCHEMA`. Change a block only to code that checks clean.
|
|
4958
|
+
* @type {readonly import("./commands.d.mts").HelpSnippet[]}
|
|
4959
|
+
*/
|
|
4960
|
+
export const HELP_SNIPPETS = Object.freeze([
|
|
4961
|
+
{
|
|
4962
|
+
name: "chart",
|
|
4963
|
+
topic: "data",
|
|
4964
|
+
path: "pages/chart.tsx",
|
|
4965
|
+
before: `import { useLive } from "@ezship/react";
|
|
4966
|
+
import { Bar, BarChart, ResponsiveContainer, Tooltip, XAxis } from "recharts";
|
|
4967
|
+
|
|
4968
|
+
/** Order totals by status. */
|
|
4969
|
+
export default function Chart() {
|
|
4970
|
+
const stats = useLive.aggregate("orders", { group: ["status"], sum: ["amount"] });
|
|
4971
|
+
return (
|
|
4972
|
+
`,
|
|
4973
|
+
code: `<ResponsiveContainer height={240}><BarChart data={stats.rows}>
|
|
4974
|
+
<XAxis dataKey="group.status" /><Tooltip /><Bar dataKey="sum.amount" /></BarChart></ResponsiveContainer>
|
|
4975
|
+
`,
|
|
4976
|
+
after: ` );
|
|
4977
|
+
}
|
|
4978
|
+
`,
|
|
4979
|
+
},
|
|
4980
|
+
{
|
|
4981
|
+
name: "relations",
|
|
4982
|
+
topic: "data",
|
|
4983
|
+
path: "components/Analyses.tsx",
|
|
4984
|
+
before: `import { useLive } from "@ezship/react";
|
|
4985
|
+
|
|
4986
|
+
/** Analyses of received samples, with what each references. */
|
|
4987
|
+
export default function Analyses({ search }: { search: string }) {
|
|
4988
|
+
`,
|
|
4989
|
+
code: `const { rows } = useLive.query("analysis", {
|
|
4990
|
+
where: { "sample_id.status": "received", or: [{ code: { contains: search } }, { ref: { contains: search } }] }, // paths filter before paging
|
|
4991
|
+
include: { sample_id: ["code"], "sample_id.client_id": ["name"], analyst: ["name"], method_instrument: { instrument_id: ["title"] } },
|
|
4992
|
+
order: ["sort_key nulls last"],
|
|
4993
|
+
});
|
|
4994
|
+
`,
|
|
4995
|
+
after: ` return (
|
|
4996
|
+
<ul>
|
|
4997
|
+
{rows.map((row) => (
|
|
4998
|
+
<li key={row.id}>
|
|
4999
|
+
{row.sample?.code} {row.sample?.client?.name} {row.analyst_row?.name}{" "}
|
|
5000
|
+
{row.method_instrument.map((m) => m.instrument?.title).join(", ")}
|
|
5001
|
+
</li>
|
|
5002
|
+
))}
|
|
5003
|
+
</ul>
|
|
5004
|
+
);
|
|
5005
|
+
}
|
|
5006
|
+
`,
|
|
5007
|
+
},
|
|
5008
|
+
{
|
|
5009
|
+
name: "action",
|
|
5010
|
+
topic: "forms",
|
|
5011
|
+
path: "components/HoursDialog.tsx",
|
|
5012
|
+
files: {
|
|
5013
|
+
"functions/saveHours.ts": `import { serverFunction, z } from "@ezship/react/server";
|
|
5014
|
+
|
|
5015
|
+
/** Records the hours worked on an item. */
|
|
5016
|
+
export default serverFunction(
|
|
5017
|
+
z.object({ itemId: z.string(), hours: z.number() }),
|
|
5018
|
+
async ({ db }, input) => {
|
|
5019
|
+
await db.update("items", input.itemId, { hours: input.hours });
|
|
5020
|
+
},
|
|
5021
|
+
);
|
|
5022
|
+
`,
|
|
5023
|
+
},
|
|
5024
|
+
before: `import { startTransition, useActionState, useState } from "react";
|
|
5025
|
+
import { attempt } from "@ezship/react";
|
|
5026
|
+
import saveHours from "../functions/saveHours";
|
|
5027
|
+
|
|
5028
|
+
/** A dialog's body that saves the hours worked on an item. */
|
|
5029
|
+
export default function HoursDialog({
|
|
5030
|
+
item,
|
|
5031
|
+
onClose,
|
|
5032
|
+
}: {
|
|
5033
|
+
item: { id: string };
|
|
5034
|
+
onClose: () => void;
|
|
5035
|
+
}) {
|
|
5036
|
+
`,
|
|
5037
|
+
code: `const [hours, setHours] = useState("");
|
|
5038
|
+
const [error, save, saving] = useActionState(attempt(async () => {
|
|
5039
|
+
const h = parseFloat(hours);
|
|
5040
|
+
if (isNaN(h) || h < 0) throw new Error("Enter a valid number of hours.");
|
|
5041
|
+
await saveHours({ itemId: item.id, hours: h }); // or db.update(...); a failure becomes the error
|
|
5042
|
+
onClose();
|
|
5043
|
+
}), null);
|
|
5044
|
+
return (
|
|
5045
|
+
<>
|
|
5046
|
+
{error ? <div className="notice danger">{error}</div> : null}
|
|
5047
|
+
<input value={hours} onChange={(e) => setHours(e.target.value)} />
|
|
5048
|
+
<button type="button" disabled={saving} onClick={() => startTransition(save)}>Save</button>
|
|
5049
|
+
</>
|
|
5050
|
+
);
|
|
5051
|
+
`,
|
|
5052
|
+
after: `}
|
|
5053
|
+
`,
|
|
5054
|
+
},
|
|
5055
|
+
{
|
|
5056
|
+
name: "session",
|
|
5057
|
+
topic: "frame",
|
|
5058
|
+
tree: "global",
|
|
5059
|
+
path: "session.ts",
|
|
5060
|
+
code: `import type { DateString } from "@ezship/react";
|
|
5061
|
+
import type { Company } from "global/db/types";
|
|
5062
|
+
export type Provided = { company: Company; roles: string[]; isAdmin: boolean }; // what the Shell provides
|
|
5063
|
+
export type Saved = { activeCompanyId: string | null; favorites: string[] }; // kept across sign-outs and devices
|
|
5064
|
+
export type SignedIn = { range: { from: DateString; to: DateString } | null }; // cleared when the viewer signs out
|
|
5065
|
+
export const defaults: Saved & SignedIn = { activeCompanyId: null, favorites: [], range: null };
|
|
5066
|
+
`,
|
|
5067
|
+
},
|
|
5068
|
+
{
|
|
5069
|
+
name: "hook",
|
|
5070
|
+
topic: "frame",
|
|
5071
|
+
path: "hooks/useOpenOrders.ts",
|
|
5072
|
+
before: `/** A customer's open orders and their total. */
|
|
5073
|
+
`,
|
|
5074
|
+
code: `import { useLive } from "@ezship/react";
|
|
5075
|
+
export default function useOpenOrders(customerId: string) {
|
|
5076
|
+
const orders = useLive.query("orders", { where: { customer_id: customerId, status: "open" } });
|
|
5077
|
+
const total = useLive.aggregate("orders", { where: { customer_id: customerId, status: "open" }, sum: ["amount"] });
|
|
5078
|
+
return { orders: orders.rows, loading: orders.loading, total: total.rows[0]?.sum.amount ?? 0 };
|
|
5079
|
+
}
|
|
5080
|
+
`,
|
|
5081
|
+
},
|
|
5082
|
+
{
|
|
5083
|
+
name: "function",
|
|
5084
|
+
topic: "functions",
|
|
5085
|
+
path: "functions/save.ts",
|
|
5086
|
+
before: `/** Saves a new order. */
|
|
5087
|
+
`,
|
|
5088
|
+
code: `import { serverFunction, z } from "@ezship/react/server";
|
|
5089
|
+
export default serverFunction(z.object({ title: z.string().min(1) }), async ({ db }, input) => {
|
|
5090
|
+
return db.insert("orders", input);
|
|
5091
|
+
});
|
|
5092
|
+
`,
|
|
5093
|
+
},
|
|
5094
|
+
{
|
|
5095
|
+
name: "many-rows",
|
|
5096
|
+
topic: "functions",
|
|
5097
|
+
path: "functions/syncPage.ts",
|
|
5098
|
+
before: `import { serverFunction, z } from "@ezship/react/server";
|
|
5099
|
+
|
|
5100
|
+
/** Marks one page of items synced and says whether more remain. */
|
|
5101
|
+
export default serverFunction(z.object({}), async ({ db }) => {
|
|
5102
|
+
`,
|
|
5103
|
+
code: `const { more } = await db.updateMany("items", { where: { synced: { ne: true } }, limit: 100 }, { synced: true });
|
|
5104
|
+
return { more };
|
|
5105
|
+
`,
|
|
5106
|
+
after: `});
|
|
5107
|
+
`,
|
|
5108
|
+
},
|
|
5109
|
+
{
|
|
5110
|
+
name: "timed-loop",
|
|
5111
|
+
topic: "functions",
|
|
5112
|
+
path: "functions/syncSome.ts",
|
|
5113
|
+
before: `import { serverFunction, z } from "@ezship/react/server";
|
|
5114
|
+
|
|
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 }) => {
|
|
5117
|
+
`,
|
|
5118
|
+
code: `const { rows, truncated } = await db.query("items", { where: { synced: { ne: true } }, limit: 500 });
|
|
5119
|
+
let done = 0;
|
|
5120
|
+
for (const row of rows) {
|
|
5121
|
+
if (timeLeft() === 0) break;
|
|
5122
|
+
await db.update("items", row.id, { synced: true });
|
|
5123
|
+
done++;
|
|
5124
|
+
}
|
|
5125
|
+
return { more: truncated || done < rows.length };
|
|
5126
|
+
`,
|
|
5127
|
+
after: `});
|
|
5128
|
+
`,
|
|
5129
|
+
},
|
|
5130
|
+
{
|
|
5131
|
+
name: "lib",
|
|
5132
|
+
topic: "functions",
|
|
5133
|
+
tree: "global",
|
|
5134
|
+
path: "lib/accounting.ts",
|
|
5135
|
+
before: `/** Guards the accounting periods share. */
|
|
5136
|
+
`,
|
|
5137
|
+
code: `import type { Database } from "@ezship/react/server";
|
|
5138
|
+
export async function periodGuard(db: Database, date: string) {
|
|
5139
|
+
const [closed] = await db.list("accounting_periods", { where: { closed: 1, ends_on: { gte: date } }, limit: 1 });
|
|
5140
|
+
if (closed) throw new Error(\`The period ending \${closed.ends_on} is closed.\`);
|
|
5141
|
+
}
|
|
5142
|
+
`,
|
|
5143
|
+
},
|
|
5144
|
+
]);
|
|
5145
|
+
|
|
5146
|
+
/** The Tables `HELP_SNIPPETS` are checked against; no topic prints it. */
|
|
5147
|
+
export const HELP_SNIPPET_SCHEMA = `CREATE TABLE companies (name TEXT);
|
|
5148
|
+
CREATE TABLE orders (
|
|
5149
|
+
title TEXT,
|
|
5150
|
+
customer_id TEXT,
|
|
5151
|
+
status TEXT CHECK (status IN ('open', 'shipped', 'paid')),
|
|
5152
|
+
amount MONEY
|
|
5153
|
+
);
|
|
5154
|
+
CREATE TABLE items (title TEXT, hours REAL, synced BOOLEAN);
|
|
5155
|
+
CREATE TABLE accounting_periods (ends_on DATE, closed INTEGER);
|
|
5156
|
+
CREATE TABLE client (name TEXT);
|
|
5157
|
+
CREATE TABLE sample (
|
|
5158
|
+
code TEXT,
|
|
5159
|
+
status TEXT CHECK (status IN ('due', 'received')),
|
|
5160
|
+
client_id REFERENCES client
|
|
5161
|
+
);
|
|
5162
|
+
CREATE TABLE instrument (title TEXT);
|
|
5163
|
+
CREATE TABLE analysis (
|
|
5164
|
+
code TEXT,
|
|
5165
|
+
ref TEXT,
|
|
5166
|
+
sort_key INTEGER,
|
|
5167
|
+
sample_id REFERENCES sample,
|
|
5168
|
+
analyst MEMBER
|
|
5169
|
+
);
|
|
5170
|
+
CREATE TABLE method_instrument (
|
|
5171
|
+
analysis_id REFERENCES analysis,
|
|
5172
|
+
instrument_id REFERENCES instrument
|
|
5173
|
+
);
|
|
5174
|
+
CREATE INDEX ON method_instrument (analysis_id);
|
|
5175
|
+
`;
|
|
5176
|
+
|
|
5177
|
+
/** A topic's block as it prints: `HELP_SNIPPETS`' code, indented under the sentence that introduces it. @param {string} name */
|
|
5178
|
+
function snippet(name) {
|
|
5179
|
+
const found = HELP_SNIPPETS.find((s) => s.name === name);
|
|
5180
|
+
if (!found) throw new Error(`No help snippet "${name}"`);
|
|
5181
|
+
return found.code
|
|
5182
|
+
.trimEnd()
|
|
5183
|
+
.split("\n")
|
|
5184
|
+
.map((l) => ` ${l}`)
|
|
5185
|
+
.join("\n");
|
|
5186
|
+
}
|
|
4505
5187
|
|
|
4506
5188
|
/** `ez help data`: reading and writing the App Database from pages. */
|
|
4507
5189
|
const DATA_TOPIC = `Data: reading and writing the App Database from pages, components and hooks (all from @ezship/react).
|
|
4508
5190
|
Tables belong to the Instance: every Site shares them. Declare them in global/db/schema.sql (\`ez help db\`);
|
|
4509
5191
|
types come from \`import type { Order } from "global/db/types"\`, and rows are Row<"orders">.
|
|
4510
|
-
|
|
4511
|
-
|
|
4512
|
-
|
|
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
|
|
4513
5199
|
useLive.count("orders", { where: { status: "shipped" } }) -> the complete count, undefined while loading
|
|
4514
5200
|
useLive.aggregate("orders", { group: ["status"], sum: ["amount"] }) -> { rows: [{ group, count, sum }], truncated, loading, version }
|
|
4515
|
-
|
|
4516
|
-
|
|
4517
|
-
db.
|
|
5201
|
+
Charts are recharts (ADR 0209), fed an aggregate's rows (stats = the useLive.aggregate above):
|
|
5202
|
+
${snippet("chart")}
|
|
5203
|
+
db.get(table, id) / db.count(table, { where }) / db.aggregate(table, query) -> one-shot, in event handlers
|
|
4518
5204
|
db.insert("orders", { customer, status: "new" }); db.update("orders", id, { status: "ready" }); db.delete("orders", id)
|
|
4519
5205
|
db.update("orders", id, { status: "paid" }, { why: "Invoice paid by card" }) -> the reason lands in that write's History row
|
|
4520
5206
|
db.settings("company_settings") -> a SINGLETON Table's row or null
|
|
@@ -4525,23 +5211,30 @@ types come from \`import type { Order } from "global/db/types"\`, and rows are R
|
|
|
4525
5211
|
today(), toDate(2026, 3, 1), toDate(date), toEpoch("2026-03-01"), now() -> DATE (DateString) and TIMESTAMP (EpochMs) values
|
|
4526
5212
|
toCents("1,234.50"), toCents(12.5), fromCents(cents) -> MONEY values (whole cents; null when unreadable)
|
|
4527
5213
|
where: { col: value } is equality ({ col: null } is IS NULL); { col: { gte: 2 } } uses eq ne lt lte gt gte in
|
|
4528
|
-
nin like null has; or: [{ ... }, { ... }]; and: [{ or: [...] }, { or: [...] }] for
|
|
4529
|
-
|
|
4530
|
-
[runtime]
|
|
4531
|
-
|
|
4532
|
-
|
|
4533
|
-
and
|
|
4534
|
-
|
|
4535
|
-
|
|
4536
|
-
|
|
4537
|
-
|
|
4538
|
-
|
|
4539
|
-
|
|
4540
|
-
|
|
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.
|
|
5232
|
+
${snippet("relations")}
|
|
5233
|
+
-> row.sample?.code, row.sample?.client?.name, row.analyst_row?.name (an actor), row.method_instrument[i].instrument?.title
|
|
4541
5234
|
A <name>_id include lands on row.<name>, <name>_ids (an id list) on row.<name> as an array, any other column c
|
|
4542
5235
|
on row.c_row; a child Table on row.<child> (up to 100, oldest first; truncatedChildren says more exist; its
|
|
4543
5236
|
column needs an index). Unreadable rows are null or left out. { ids: { has: id } } tests an id list.
|
|
4544
|
-
db.
|
|
5237
|
+
db.query, db.list and aggregate take the same where and include, in pages, functions and rules.
|
|
4545
5238
|
History: every Table has a read-only \`<table>_history\` the platform writes on every change, with the actor
|
|
4546
5239
|
and the write's why. [advice] Never build a log or audit table; an activity feed reads the History
|
|
4547
5240
|
(\`ez help db\`). The actors view is read-only: match History's by to actors.id, show the current name, and
|
|
@@ -4552,7 +5245,7 @@ Refused writes reject with a WriteError: \`catch (e) { if (e instanceof WriteErr
|
|
|
4552
5245
|
|
|
4553
5246
|
/** `ez help forms`: writes from the UI, actions and the schema-driven record components. */
|
|
4554
5247
|
const FORMS_TOPIC = `Forms and actions: how the UI writes, and the schema's record components.
|
|
4555
|
-
Records from the schema (ADR
|
|
5248
|
+
Records from the schema (ADR 0222): reach for these before writing a list, a form, a picker or a reference
|
|
4556
5249
|
label by hand. They draw labels, inputs, choices and refusals from global/db/schema.sql (LABEL, DISPLAY,
|
|
4557
5250
|
CHECK, REFERENCES; \`ez help db\`), so [advice] never re-declare those in Site code.
|
|
4558
5251
|
<RecordList table="dealers" columns={["customer_code", "name", "credit_hold"]} search={["name", "customer_code"]}
|
|
@@ -4566,6 +5259,18 @@ CHECK, REFERENCES; \`ez help db\`), so [advice] never re-declare those in Site c
|
|
|
4566
5259
|
<MemberPicker value={m} onChange={setM} />, <CellValue table="dealers" column="credit_hold" value={v} />
|
|
4567
5260
|
schema.table("dealers") -> { label, plural, display, columns, referencedBy, ... }; schema.label("dealers", row)
|
|
4568
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.
|
|
4569
5274
|
A one-click write (delete, toggle) is onClick={() => run(() => db.delete("orders", id))}: run() awaits it and
|
|
4570
5275
|
shows the standard failure notice.
|
|
4571
5276
|
A write with fields or a pending state (a modal's Save, a form) is an action, which replaces the saving flag,
|
|
@@ -4573,29 +5278,21 @@ the error state and the try/catch/finally around the write. attempt() makes the
|
|
|
4573
5278
|
show: null on success, otherwise errorMessage of what it threw (a failed check, a refused write, a server
|
|
4574
5279
|
function's rejection). The dialog stays open with the message; the action closes it on success. Keep the
|
|
4575
5280
|
fields in useState and read them in the action; server functions take their typed input, never FormData.
|
|
4576
|
-
|
|
4577
|
-
const [error, save, saving] = useActionState(attempt(async () => {
|
|
4578
|
-
const h = parseFloat(hours);
|
|
4579
|
-
if (isNaN(h) || h < 0) throw new Error("Enter a valid number of hours.");
|
|
4580
|
-
await saveHours({ itemId: item.id, hours: h }); // or db.update(...); a failure becomes the error
|
|
4581
|
-
onClose();
|
|
4582
|
-
}), null);
|
|
4583
|
-
...
|
|
4584
|
-
{error ? <div className="notice danger">{error}</div> : null}
|
|
4585
|
-
<input value={hours} onChange={(e) => setHours(e.target.value)} />
|
|
4586
|
-
<button type="button" disabled={saving} onClick={() => startTransition(save)}>Save</button>
|
|
5281
|
+
${snippet("action")}
|
|
4587
5282
|
Dispatch the action from onClick={() => startTransition(save)} (both from react), or from a form: <form
|
|
4588
5283
|
id="hours" action={save} noValidate> around the fields and a Save button with form="hours" (it may sit in a
|
|
4589
5284
|
footer outside the form). A form submits on Enter, but every <button> inside it without type="button" submits
|
|
4590
5285
|
it too, a child component's (a picker's) included: use the form only when its buttons are typed. noValidate
|
|
4591
|
-
leaves validation to the action.
|
|
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
|
|
4592
5289
|
a form, formAction or a transition (form-action). useFormStatus() (from @ezship/react) gives pending to a
|
|
4593
5290
|
child component inside the form; useTransition gives a pending flag to any async work; useOptimistic shows a
|
|
4594
5291
|
value before its write lands. An action that throws outside attempt() shows its error in place of the page.
|
|
4595
5292
|
There is no Modal in the Framework: a dialog is your own component (\`ez help recipes\`, modal-save).
|
|
4596
5293
|
errorMessage(e) is the message of anything a catch caught. [check, warning] Never cast it (no-cast).`;
|
|
4597
5294
|
|
|
4598
|
-
/** `ez help frame`: provided values, Session State, query parameters and custom hooks (ADRs
|
|
5295
|
+
/** `ez help frame`: provided values, Session State, query parameters and custom hooks (ADRs 0214 and 0209). */
|
|
4599
5296
|
const FRAME_TOPIC = `The frame: provided values, Session State, query parameters, custom hooks, the Shell and the viewer.
|
|
4600
5297
|
Pick by what the value is:
|
|
4601
5298
|
data the frame works out once (who the viewer is in the app's terms) -> provided values: useProvided()
|
|
@@ -4605,12 +5302,7 @@ Pick by what the value is:
|
|
|
4605
5302
|
[advice] Never pass the frame's values down as props; read useProvided() where they are needed.
|
|
4606
5303
|
global/session.ts declares them (all four exports; each type may be {}; Admins push it, and it takes effect at
|
|
4607
5304
|
once for every Site, ez help lifecycle):
|
|
4608
|
-
|
|
4609
|
-
import type { Company } from "global/db/types";
|
|
4610
|
-
export type Provided = { company: Company; roles: string[]; isAdmin: boolean }; // what the Shell provides
|
|
4611
|
-
export type Saved = { activeCompanyId: string | null; favorites: string[] }; // kept across sign-outs and devices
|
|
4612
|
-
export type SignedIn = { range: { from: DateString; to: DateString } | null }; // cleared when the viewer signs out
|
|
4613
|
-
export const defaults: Saved & SignedIn = { activeCompanyId: null, favorites: [], range: null };
|
|
5305
|
+
${snippet("session")}
|
|
4614
5306
|
[check] Saved and SignedIn are written like a JSON TYPE (string, number, boolean, null, DateString, EpochMs,
|
|
4615
5307
|
literals, { ... }, T[], Record<string, T>; no named types), every key camelCase and required (session-shape).
|
|
4616
5308
|
[runtime] The Host checks every write against them; a value is at most 4 KB of JSON, 32 keys per Instance.
|
|
@@ -4631,16 +5323,11 @@ access by it; a function given activeCompanyId still checks in the App Database
|
|
|
4631
5323
|
that company.
|
|
4632
5324
|
useSearchParam("state") -> that query parameter of the current route, string | null (re-renders when it changes)
|
|
4633
5325
|
<Link site="dispatch" to="/orders?state=needs_dispatch">; useNavigate()("/orders?driver=" + encodeURIComponent(id))
|
|
4634
|
-
Custom hooks (ADR
|
|
5326
|
+
Custom hooks (ADR 0209): when a second page or component needs the same live query, Session State or derived
|
|
4635
5327
|
values, move them into \`hooks/use<Name>.ts\` (or \`global/hooks/use<Name>.ts\` when several Sites share it,
|
|
4636
5328
|
imported as "global/hooks/use<Name>") rather than copying them. A hook has a component's imports and rules,
|
|
4637
5329
|
calls hooks at its top level and returns values, never markup:
|
|
4638
|
-
|
|
4639
|
-
export default function useOpenOrders(customerId: string) {
|
|
4640
|
-
const orders = useLive("orders", { where: { customer_id: customerId, status: "open" } });
|
|
4641
|
-
const total = useLive.aggregate("orders", { where: { customer_id: customerId, status: "open" }, sum: ["amount"] });
|
|
4642
|
-
return { orders, total: total.rows[0]?.sum.amount ?? 0 };
|
|
4643
|
-
}
|
|
5330
|
+
${snippet("hook")}
|
|
4644
5331
|
[check, warning] Call hooks at the top of a component, never in a loop, a callback or a condition (react-hooks/rules-of-hooks, hooks-order).
|
|
4645
5332
|
A hook is for React state and live data; logic that needs neither belongs in global/lib (ez help functions).
|
|
4646
5333
|
The Shell and navigation: App.tsx renders the Site's links once in <Nav>{links}</Nav>; the global Shell draws
|
|
@@ -4651,53 +5338,93 @@ The viewer: sign-in and membership are the platform's. useAuth() -> { user: { id
|
|
|
4651
5338
|
membership: "active" | "blocked" | null, me (the viewer as a MEMBER column holds them), groups, loading };
|
|
4652
5339
|
signIn() and signOut() are their own imports, not fields of useAuth().`;
|
|
4653
5340
|
|
|
4654
|
-
/** `ez help functions`: server functions, useCall and Global lib modules (ADRs
|
|
5341
|
+
/** `ez help functions`: server functions, useCall and Global lib modules (ADRs 0228 and 0210). */
|
|
4655
5342
|
const FUNCTIONS_TOPIC = `Server functions, useCall and shared logic.
|
|
4656
5343
|
Server functions belong to this Site's Version and deploy with its UI. In functions/save.ts:
|
|
4657
|
-
|
|
4658
|
-
export default serverFunction(z.object({ title: z.string().min(1) }), async ({ db }, input) => {
|
|
4659
|
-
return db.insert("orders", input);
|
|
4660
|
-
});
|
|
5344
|
+
${snippet("function")}
|
|
4661
5345
|
UI imports ./functions/save (../functions/save from a page or component) and calls save({ title }) from an
|
|
4662
5346
|
event handler or an action, or useCall(summary, { from, to }) -> { result, loading, error, refresh } to run
|
|
4663
5347
|
one when the page opens. useCall takes any async function of its input, so a report too big for a function's
|
|
4664
5348
|
limits can load from the page: useCall(({ companyId }) => computeAging(db, companyId), { companyId }), with
|
|
4665
5349
|
computeAging a global/lib function given the page's db; its db calls are separate requests under the same
|
|
4666
5350
|
access rules, so prefer aggregates to loops. Neither form is live: refresh() reloads it.
|
|
4667
|
-
The handler's context: { db, user, session, documents, integration, members } (ez help integrations,
|
|
4668
|
-
documents). The db has the caller's access rules and list/query/aggregate/count/get/insert/update/delete
|
|
4669
|
-
typed; user is the validated caller.
|
|
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
|
|
5353
|
+
insertMany/updateMany/deleteMany (below), typed; user is the validated caller.
|
|
4670
5354
|
[runtime] Each call is one transaction: all writes and History commit together or all roll back, so never wrap
|
|
4671
5355
|
a handler's body in db.transaction (redundant-transaction warns); one inside a try still fails the call when
|
|
4672
5356
|
its failure is caught. A repeated unique key rolls the call back: check before you insert. Await database calls.
|
|
4673
|
-
[runtime]
|
|
4674
|
-
|
|
5357
|
+
[runtime] A call runs as if it were alone: no other write lands between what it reads and what it writes, so a
|
|
5358
|
+
check then a write holds, and a value read and written back never loses an update. To keep this the Host may run
|
|
5359
|
+
a call twice; the first run leaves nothing and the caller gets one answer. Code that calls an integration has
|
|
5360
|
+
this only from its first write or inside db.transaction (ez help integrations). A page has none of it across
|
|
5361
|
+
calls: each db call from a page is its own transaction, so a check that must hold when the write lands belongs in
|
|
5362
|
+
a function, a Table rule or a workflow action, which run inside the write.
|
|
5363
|
+
[runtime] Limits per call: 10-second deadline, 5-second database deadline (below), 32-MB JS heap, 1,000 database
|
|
5364
|
+
operations, 256-KB JSON input and output. No files, network (but Integrations), packages, timers
|
|
4675
5365
|
or locales: there is no Intl, and toLocale*String and localeCompare ignore locales and time zones, so return
|
|
4676
5366
|
numbers and ISO dates and format in the page (server-locale warns). A stale browser call asks for a reload.
|
|
5367
|
+
[runtime] The database deadline is usually the first limit a call meets. From its first database operation
|
|
5368
|
+
until it returns, reads, computation and the commit included, a call has 5 seconds, and one database step 2 seconds;
|
|
5369
|
+
past either, the whole call rolls back ("Function database deadline exceeded"). Code that calls an integration
|
|
5370
|
+
counts from its first write instead (ez help integrations). So does a call the Host has not yet seen write, so
|
|
5371
|
+
a function can pass once and fail the next time: plan for the first operation. A write takes from about 1 ms on
|
|
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
|
|
5373
|
+
writes per call, and write many rows with insertMany, updateMany or deleteMany (below), one operation each. Other
|
|
5374
|
+
writes wait while a call holds the database, so keep what people wait on short.
|
|
5375
|
+
[runtime] On a Host that several Instances share, an Instance's calls share 1 second of execution and 250 ms of
|
|
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
|
|
5377
|
+
Host with one customer has no such budget; code that must run on both retries a 429.
|
|
5378
|
+
[runtime] Many rows at once, in server code only (not a page, a Table rule or a lib module's Database):
|
|
5379
|
+
db.insertMany(table, rows, { why, action }) writes up to 1,000 rows and answers { count, ids };
|
|
5380
|
+
db.updateMany(table, { where, limit }, patch, { why }) and db.deleteMany(table, { where, limit }, { why }) take up
|
|
5381
|
+
to limit rows (1,000 at most and by default) in id order and answer { count, more }, where more says where matched
|
|
5382
|
+
others. Each is one database operation and means exactly that many single writes: access rules, defaults, Table
|
|
5383
|
+
rules, workflows (the status column is refused as in an update), unique keys and a History row each. A refusal
|
|
5384
|
+
rolls the call back, so none of its rows stand: that includes a row where matches that the caller may read but not
|
|
5385
|
+
write (403, naming the row), so narrow where to rows it may write. The 256-KB limit holds for what you pass.
|
|
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:
|
|
5400
|
+
${snippet("many-rows")}
|
|
5401
|
+
Page by a condition the write changes: a patch that leaves where true matches the same rows again. The database
|
|
5402
|
+
deadline holds for the whole operation, so on a Table with rules choose a limit well inside 1,000.
|
|
4677
5403
|
[check] Each function file is one default serverFunction(...) call; keep private helpers inside that file, or in
|
|
4678
|
-
a
|
|
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,
|
|
4679
5405
|
{ access: "group(payroll)", authority: "site" }) (ez help access); { api: true } also lets an API Key call it
|
|
4680
5406
|
(ez help api).
|
|
4681
|
-
Test with \`ez function call save '{"title":"Test"}' [--preview <name>]\`; its writes are real (ask first).
|
|
4682
|
-
|
|
4683
|
-
|
|
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
|
|
4684
5415
|
workflows import them by name (\`import { periodGuard } from "global/lib/accounting"\`).
|
|
4685
5416
|
[check] A lib module has named exports only and imports only other lib modules (\`./names\` or
|
|
4686
5417
|
\`global/lib/names\`) and \`import type\` from \`@ezship/react/server\` and \`global/db/types\`: pure TypeScript with
|
|
4687
5418
|
the Site rules (no packages, network, timers, storage, DOM or classes). It runs in server functions too, so
|
|
4688
5419
|
format for display in pages, not in lib. Whatever reads or writes takes the database as its first argument,
|
|
4689
5420
|
typed \`Database\` (\`Row\`, \`Query\`, \`TableName\` and the other data types come from the same module):
|
|
4690
|
-
|
|
4691
|
-
export async function periodGuard(db: Database, date: string) {
|
|
4692
|
-
const [closed] = await db.list("accounting_periods", { where: { closed: 1, ends_on: { gte: date } }, limit: 1 });
|
|
4693
|
-
if (closed) throw new Error(\`The period ending \${closed.ends_on} is closed.\`);
|
|
4694
|
-
}
|
|
5421
|
+
${snippet("lib")}
|
|
4695
5422
|
A page passes \`db\` from @ezship/react, a server function its \`db\`, so one guard runs in both and, inside a
|
|
4696
5423
|
function, in its transaction. [advice] Move code to lib when a second file needs it rather than copying it.
|
|
4697
5424
|
\`ez global check\` checks lib against every Site; a Site's \`ez check\` and \`ez preview\` use the lib in your
|
|
4698
5425
|
Global Working Copy, unpushed edits included; \`ez deploy\` uses the pushed lib (ez help lifecycle).`;
|
|
4699
5426
|
|
|
4700
|
-
/** `ez help integrations` (
|
|
5427
|
+
/** `ez help integrations` (ADR 0231). */
|
|
4701
5428
|
const INTEGRATIONS_TOPIC = `Integrations let server code (a function, job, listener) reach another service without seeing its
|
|
4702
5429
|
credentials. [runtime] Pages and local functions have no integrations, and there is no fetch anywhere.
|
|
4703
5430
|
An Admin sets one in a terminal (\`ez integration set stripe --origin https://api.stripe.com --header
|
|
@@ -4722,7 +5449,11 @@ can read the same stock and both write; wrap a read-check-write in db.transactio
|
|
|
4722
5449
|
takes the writer at once (no integration call inside or after it). A rollback never undoes a request: pass
|
|
4723
5450
|
the service an idempotency key where it takes one, and remember a timed-out POST may have happened.
|
|
4724
5451
|
[runtime] Per call: 5 requests, each within the integration's timeout (default 10 s, at most 30), 60 s in all,
|
|
4725
|
-
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.
|
|
5454
|
+
[runtime] While a service answers, the call's 10-second deadline pauses and it holds no database, so neither its
|
|
5455
|
+
requests nor its reads before the first write count toward the 5-second database deadline (ez help functions).
|
|
5456
|
+
That deadline starts at the first write or db.transaction: the writes and whatever follows them must fit in it.
|
|
4726
5457
|
An Admin can also give a binding values (\`ez integration value stripe --header Stripe-Version 2024-06-20\`,
|
|
4727
5458
|
or \`--secret\` for a second key, read like the credential): headers and parameters the Host adds to every
|
|
4728
5459
|
request. [runtime] Code cannot set or override a header or parameter the binding sets. Values belong on the
|
|
@@ -4733,10 +5464,11 @@ are not built yet: every call on one is refused (grant), and \`context.integrati
|
|
|
4733
5464
|
[advice] Put a typed wrapper for a service in global/lib (it imports the type IntegrationClient from
|
|
4734
5465
|
@ezship/react/server and takes the client as an argument, like the database); defaults code may override
|
|
4735
5466
|
belong there, not on the binding.
|
|
4736
|
-
\`ez integration test <name> <path>\` makes one request
|
|
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
|
|
4737
5469
|
their refusals. A deploy warns when the code names an integration the Instance has not set.`;
|
|
4738
5470
|
|
|
4739
|
-
/** `ez help jobs`: scheduled jobs and listeners (ADRs
|
|
5471
|
+
/** `ez help jobs`: scheduled jobs and listeners (ADRs 0230 and 0231). */
|
|
4740
5472
|
const JOBS_TOPIC = `Scheduled jobs and listeners: server code nothing in the browser calls.
|
|
4741
5473
|
Scheduled jobs belong to the Instance, not a Site: they live in the Global Workspace and run from its pushed
|
|
4742
5474
|
schedules.json. In global/jobs/closeDay.ts (\`ez global put jobs/closeDay.ts\`):
|
|
@@ -4745,18 +5477,29 @@ schedules.json. In global/jobs/closeDay.ts (\`ez global put jobs/closeDay.ts\`):
|
|
|
4745
5477
|
// run.due is the scheduled time (ISO, UTC): use it, not the clock, so a run is idempotent per due time
|
|
4746
5478
|
});
|
|
4747
5479
|
and in global/schedules.json: [{ "name": "nightly", "cron": "0 2 * * *", "job": "closeDay", "input": { "days": 1 } }]
|
|
4748
|
-
[check] Cron is five UTC fields (minute hour day-of-month month day-of-week
|
|
4749
|
-
|
|
4750
|
-
|
|
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>.
|
|
4751
5486
|
Nothing imports a job and no browser can call one; it imports what \`ez help files\` lists for Global jobs, so
|
|
4752
5487
|
logic it shares with a Site goes in global/lib and its constants in global/constants.
|
|
4753
5488
|
[runtime] \`ez global push\` activates the schedules and the jobs at once ("Takes effect now"); only Admins
|
|
4754
5489
|
change schedules.json. Previews never run them. A job sees the Tables and columns a Preview or Deploy has
|
|
4755
5490
|
created: push alone creates none. Each due time runs at most once; after the Host was down, only the latest
|
|
4756
|
-
missed time runs. One run has a function's
|
|
4757
|
-
|
|
5491
|
+
missed time runs. One run has a function's limits, the 5-second database deadline included (ez help functions),
|
|
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.
|
|
5498
|
+
\`ez schedule list\` shows each schedule's next due time and last run, \`ez schedule runs <name>\` its recent runs and errors,
|
|
4758
5499
|
and \`ez schedule run <name>\` runs it now (writes are real). \`ez schedule pause <name>\` stops its due times
|
|
4759
|
-
with no push; \`ez schedule resume <name>\` starts them again from now,
|
|
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.
|
|
4760
5503
|
Listeners receive webhooks: other services post events to the Site, verified with the secret the service
|
|
4761
5504
|
issued. In listeners/stripeEvents.ts:
|
|
4762
5505
|
import { listener, z } from "@ezship/react/server";
|
|
@@ -4773,13 +5516,16 @@ with Site authority, and integrations, plus event: { id, deliveryId, receivedAt,
|
|
|
4773
5516
|
JSON (or its text), checked by the schema. Nothing imports a listener; browsers cannot post to one.
|
|
4774
5517
|
After deploying, \`ez listener list\` shows the URL to give the sending service; the person who registers it
|
|
4775
5518
|
runs \`ez listener secret <name>\` in a terminal with the secret the service issued (never through this
|
|
4776
|
-
conversation); until then every delivery is refused.
|
|
4777
|
-
|
|
4778
|
-
|
|
4779
|
-
|
|
4780
|
-
|
|
4781
|
-
|
|
4782
|
-
|
|
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). */
|
|
4783
5529
|
const API_TOPIC = `The Data API lets another system (a sync job, a reporting tool, a script on the customer's server) read
|
|
4784
5530
|
and write this Instance's data over HTTPS. Pages never use it: they have useLive and db.
|
|
4785
5531
|
An Admin creates an API Key in a terminal, from any Working Copy of the Instance: \`ez key create warehouse
|
|
@@ -4798,12 +5544,15 @@ describes what it may reach. It serves the published schema as far as the App Da
|
|
|
4798
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
|
|
4799
5545
|
<table>/aggregate, GET <table>/<id>, POST <table> (insert), PATCH and DELETE <table>/<id>, POST
|
|
4800
5546
|
<table>/<id>/actions/<action>; ?why= gives a write its reason. The change feed is the History:
|
|
4801
|
-
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.
|
|
4802
5549
|
Server functions are callable by a key only when they say so: serverFunction(input, handler, { api: true })
|
|
4803
5550
|
[check: function-options], and only on the Sites its --sites allows. [runtime] Without --sites a key calls no
|
|
4804
5551
|
functions, all means every unrestricted Site, and a Restricted Site is reached only by a key that names its id;
|
|
4805
5552
|
--sites never narrows data, which groups do. POST _ez/api/sites/<site>/functions/<name> {"input": ...} answers
|
|
4806
|
-
{"result": ...}, against that Site's deployed artifact, under the function's own access and authority
|
|
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
|
|
4807
5556
|
handler a key's user is { id: "key:<name>", email: "", name, me: null, groups }. Files: POST
|
|
4808
5557
|
_ez/api/attachments/<table>/<column>?name=<file> with the bytes, GET _ez/api/attachments/<id>.
|
|
4809
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
|
|
@@ -4811,7 +5560,7 @@ past that). A key lasts ${API_KEY_DAYS.default} days by default, at most ${API_K
|
|
|
4811
5560
|
name is never reused: to rotate, create a new key, switch the other system to it, revoke the old one.
|
|
4812
5561
|
Previews have no API.`;
|
|
4813
5562
|
|
|
4814
|
-
/** `ez help local` (ADR
|
|
5563
|
+
/** `ez help local` (ADR 0235). */
|
|
4815
5564
|
const LOCAL_TOPIC = `Local functions run on the Member's own computer, inside ezship Desktop, and never on the Host.
|
|
4816
5565
|
In local/readEmpty.ts:
|
|
4817
5566
|
import { localFunction, z } from "@ezship/react/local";
|
|
@@ -4826,7 +5575,9 @@ the Member (user), the Site (site) and desktop.dataDir, a folder the Desktop kee
|
|
|
4826
5575
|
computer; it has no db: the page saves results with db.insert or a server function.
|
|
4827
5576
|
[check] Local functions import only @ezship/react/local (localFunction, z and types), node:* built-ins (with
|
|
4828
5577
|
the prefix), constants, sibling local functions and type-only global/db/types; no packages.
|
|
4829
|
-
[runtime] One call runs at most 60 seconds
|
|
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
|
|
4830
5581
|
fails and the Framework shows a notice that the app needs ezship Desktop; useDesktop() -> { available,
|
|
4831
5582
|
version } lets a page offer manual entry instead.
|
|
4832
5583
|
[advice] Use local functions for station configuration, caches, exports and exchanging files with programs on
|
|
@@ -4834,7 +5585,7 @@ that computer; the App Database stays the shared record, and nothing in a local
|
|
|
4834
5585
|
Members or computers. Never write credentials or Host tokens to disk. Test by opening the Preview URL in
|
|
4835
5586
|
ezship Desktop (ez preview prints it; ez dev keeps it fresh).`;
|
|
4836
5587
|
|
|
4837
|
-
/** `ez help documents` (ADR
|
|
5588
|
+
/** `ez help documents` (ADR 0233). */
|
|
4838
5589
|
const DOCUMENTS_TOPIC = `Documents: PDFs from Global templates in \`global/documents/<Name>.tsx\` (\`ez global put documents/Invoice.tsx\`):
|
|
4839
5590
|
import { document, z, Document, Page, View, Text, Image, PageNumber, asset } from "@ezship/react/pdf";
|
|
4840
5591
|
export default document(
|
|
@@ -4868,6 +5619,9 @@ context and exported by @ezship/react:
|
|
|
4868
5619
|
const r = await documents.render(Invoice, data, { filename: "invoice-1.pdf", attachTo: { table: "invoices", id, column: "pdf" } });
|
|
4869
5620
|
Rendering is asynchronous: useRender(r.id) -> { status: "queued" | "rendering" | "ready" | "failed", file, error }.
|
|
4870
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.
|
|
4871
5625
|
[runtime] Every PDF is permanent; a FILE column holding its id shares it with the Table's readers, and History
|
|
4872
5626
|
keeps the ids a column held before. Input is JSON up to 1 MB; at most 200 pages.
|
|
4873
5627
|
Test a deployed one: \`ez document render Invoice '<json>'\`.`;
|
|
@@ -4889,6 +5643,10 @@ The body is Markdown, never HTML: paragraphs, # headings, **bold**, *italic*, \`
|
|
|
4889
5643
|
- and 1. lists, pipe tables (good for reports) and fenced code. The subject is one line.
|
|
4890
5644
|
link("/path") is the absolute URL of a page of this Site (of your Preview, from a Preview);
|
|
4891
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.
|
|
4892
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}
|
|
4893
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
|
|
4894
5652
|
job (one Email per person, a table of their items) stays under them.
|
|
@@ -5066,14 +5824,15 @@ import CreditLimitDialog from "../components/CreditLimitDialog";
|
|
|
5066
5824
|
|
|
5067
5825
|
/** Active customers and their credit limits; a row opens the dialog that changes one. */
|
|
5068
5826
|
export default function Credit() {
|
|
5069
|
-
const customers = useLive("customers", { where: { status: "active" }, order: ["name"] });
|
|
5827
|
+
const customers = useLive.query("customers", { where: { status: "active" }, order: ["name"] });
|
|
5070
5828
|
const [editing, setEditing] = useState<Customer | null>(null);
|
|
5071
5829
|
return (
|
|
5072
5830
|
<>
|
|
5073
5831
|
<PageHeader title="Credit limits" description="Open a customer to change their limit." />
|
|
5074
5832
|
<Panel flush>
|
|
5075
5833
|
<DataTable
|
|
5076
|
-
rows={customers}
|
|
5834
|
+
rows={customers.rows}
|
|
5835
|
+
loading={customers.loading}
|
|
5077
5836
|
columns={[
|
|
5078
5837
|
{ label: "Customer", cell: (c) => c.name },
|
|
5079
5838
|
{ label: "Limit", cell: (c) => <Money cents={c.credit_limit} />, align: "right" },
|
|
@@ -5277,6 +6036,263 @@ Site's ez check and ez preview already use your unpushed copy; ez deploy uses th
|
|
|
5277
6036
|
computes the stored total itself rather than trusting the page's. Lib modules format nothing (no Intl on the
|
|
5278
6037
|
server): the page shows cents with the starter's Money.`,
|
|
5279
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
|
+
},
|
|
5280
6296
|
]),
|
|
5281
6297
|
);
|
|
5282
6298
|
|
|
@@ -5303,11 +6319,13 @@ against the starter Global Workspace). They share one customers Table, declared
|
|
|
5303
6319
|
|
|
5304
6320
|
${RECIPES.map(recipeText).join("\n\n")}`;
|
|
5305
6321
|
|
|
5306
|
-
/** `ez help access`: the doors around the App Database's rows (ADRs
|
|
6322
|
+
/** `ez help access`: the doors around the App Database's rows (ADRs 0203 and 0225). */
|
|
5307
6323
|
const accessTopic =
|
|
5308
6324
|
() => `Access: who opens a Site, who reads and writes which rows, who runs which code.
|
|
5309
6325
|
Every Site and Preview requires a signed-in active Member; Builders are Members too. An Admin may restrict a
|
|
5310
|
-
Site to allow-lists and groups (\`ez site access\`)
|
|
6326
|
+
Site to allow-lists and groups (\`ez site access\`); the Admin who restricts it stays on its lists, so
|
|
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.
|
|
5311
6329
|
Rows: global/db/access.sql is the one place that says who reads and writes which rows. [runtime] The Host
|
|
5312
6330
|
applies it to every page, function, job and attachment request, for deployed Sites and Previews alike, from
|
|
5313
6331
|
the moment an Admin pushes it (ez help lifecycle); a row a Member may not read is "Not found".
|
|
@@ -5345,7 +6363,7 @@ export const HELP_TOPICS = Object.freeze([
|
|
|
5345
6363
|
{
|
|
5346
6364
|
name: "recipes",
|
|
5347
6365
|
summary:
|
|
5348
|
-
"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",
|
|
5349
6367
|
text: () => RECIPES_TOPIC,
|
|
5350
6368
|
},
|
|
5351
6369
|
{
|
|
@@ -5467,6 +6485,10 @@ export const COMMANDS = [
|
|
|
5467
6485
|
usage: "ez function call <name> <json> [--preview <name>]",
|
|
5468
6486
|
help: "invoke a Site function from its deployment or your Preview; writes are real",
|
|
5469
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
|
+
},
|
|
5470
6492
|
{
|
|
5471
6493
|
usage: "ez schedule list",
|
|
5472
6494
|
help: "the Instance's pushed global/schedules.json: each schedule's cron, job, next due time and last run",
|
|
@@ -5509,7 +6531,7 @@ export const COMMANDS = [
|
|
|
5509
6531
|
},
|
|
5510
6532
|
{
|
|
5511
6533
|
usage: "ez help [<topic> | all]",
|
|
5512
|
-
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",
|
|
5513
6535
|
},
|
|
5514
6536
|
{
|
|
5515
6537
|
usage: "ez status",
|
|
@@ -5530,7 +6552,7 @@ export const COMMANDS = [
|
|
|
5530
6552
|
},
|
|
5531
6553
|
{
|
|
5532
6554
|
usage: "ez check [--json]",
|
|
5533
|
-
help: "the rules, the types and a build dry run on the host, without serving anything; errors fail it, warnings do not (`ez help rules`); --json prints [{ file, line, column, rule, severity, message
|
|
6555
|
+
help: "the rules, the types and a build dry run on the host, without serving anything; errors fail it, warnings do not (`ez help rules`); --json prints [{ file, line, column, rule, severity, message }]; run it before you say a change is done (a successful ez preview is also a check)",
|
|
5534
6556
|
},
|
|
5535
6557
|
{
|
|
5536
6558
|
usage: "ez format [--check]",
|
|
@@ -5545,7 +6567,7 @@ export const COMMANDS = [
|
|
|
5545
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)",
|
|
5546
6568
|
},
|
|
5547
6569
|
{
|
|
5548
|
-
usage: "ez preview delete
|
|
6570
|
+
usage: "ez preview delete [<name>]",
|
|
5549
6571
|
help: "delete a preview (the default one when no name is given)",
|
|
5550
6572
|
},
|
|
5551
6573
|
{
|
|
@@ -5560,7 +6582,6 @@ export const COMMANDS = [
|
|
|
5560
6582
|
usage: "ez delete <path>",
|
|
5561
6583
|
help: `delete a file (${MAIN_FILE} and ${CONTEXT_FILE} cannot be deleted)`,
|
|
5562
6584
|
},
|
|
5563
|
-
{ usage: "ez rm <path>", help: "alias for delete" },
|
|
5564
6585
|
{ usage: "ez mv <from> <to>", help: "rename a file" },
|
|
5565
6586
|
{
|
|
5566
6587
|
usage: "ez config",
|
|
@@ -5584,21 +6605,20 @@ export const COMMANDS = [
|
|
|
5584
6605
|
usage: "ez site archive <id>",
|
|
5585
6606
|
help: "admins: archive a site, retaining its files, data and id",
|
|
5586
6607
|
},
|
|
5587
|
-
{ usage: "ez site rm <id>", help: "alias for site archive" },
|
|
5588
6608
|
{
|
|
5589
6609
|
usage: "ez site access",
|
|
5590
6610
|
help: "who may open this site: every builder and member, or the allow-lists",
|
|
5591
6611
|
},
|
|
5592
6612
|
{
|
|
5593
6613
|
usage: "ez site access restrict|open",
|
|
5594
|
-
help: "admins: switch between the allow-lists and everyone in the instance",
|
|
6614
|
+
help: "admins: switch between the allow-lists and everyone in the instance; whoever restricts a site stays on its lists",
|
|
5595
6615
|
},
|
|
5596
6616
|
{
|
|
5597
|
-
usage: "ez site access add|remove
|
|
6617
|
+
usage: "ez site access add|remove builder|user <who>",
|
|
5598
6618
|
help: "admins: edit the allow-lists (who is an id or email)",
|
|
5599
6619
|
},
|
|
5600
6620
|
{
|
|
5601
|
-
usage: "ez site access add|remove
|
|
6621
|
+
usage: "ez site access add|remove group <name>",
|
|
5602
6622
|
help: "admins: let a group's members (implied groups included) open the restricted site, or stop",
|
|
5603
6623
|
},
|
|
5604
6624
|
{
|
|
@@ -5614,7 +6634,7 @@ export const COMMANDS = [
|
|
|
5614
6634
|
help: "admins: change a builder's role (who is an id or email); limited builders neither push global nor create sites",
|
|
5615
6635
|
},
|
|
5616
6636
|
{
|
|
5617
|
-
usage: "ez builder remove
|
|
6637
|
+
usage: "ez builder remove <who>",
|
|
5618
6638
|
help: "admins: remove a builder (and their membership) from the instance",
|
|
5619
6639
|
},
|
|
5620
6640
|
{
|
|
@@ -5627,7 +6647,7 @@ export const COMMANDS = [
|
|
|
5627
6647
|
},
|
|
5628
6648
|
{ usage: "ez user block <who>", help: "block a member (who is an id or email)" },
|
|
5629
6649
|
{ usage: "ez user unblock <who>", help: "unblock a member" },
|
|
5630
|
-
{ usage: "ez user remove
|
|
6650
|
+
{ usage: "ez user remove <who>", help: "remove a member from the instance" },
|
|
5631
6651
|
{
|
|
5632
6652
|
usage: "ez user group add|remove <who> <group>",
|
|
5633
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",
|
|
@@ -5637,21 +6657,17 @@ export const COMMANDS = [
|
|
|
5637
6657
|
help: 'admins: upload an image, video or document once for the whole instance; site code then says asset("<name>")',
|
|
5638
6658
|
},
|
|
5639
6659
|
{ usage: "ez asset ls", help: "the instance's assets: name, type, size" },
|
|
5640
|
-
{
|
|
5641
|
-
usage: "ez asset delete|rm <name> [--force]",
|
|
5642
|
-
help: "disabled: assets cannot be deleted, even with --force; upload with a new name",
|
|
5643
|
-
},
|
|
5644
6660
|
{
|
|
5645
6661
|
usage: "ez audit [--site <id>] [--kind <kind>] [--limit N] [--before <id>]",
|
|
5646
6662
|
help: "who did what in this instance, newest first",
|
|
5647
6663
|
},
|
|
5648
6664
|
{
|
|
5649
6665
|
usage: "ez db tables",
|
|
5650
|
-
help: "every table in the app database: columns, indexes, rows
|
|
6666
|
+
help: "every table in the app database: columns, indexes, rows",
|
|
5651
6667
|
},
|
|
5652
6668
|
{
|
|
5653
6669
|
usage: "ez db schema",
|
|
5654
|
-
help: "the live schema as
|
|
6670
|
+
help: "the live schema as CREATE TABLE statements",
|
|
5655
6671
|
},
|
|
5656
6672
|
{
|
|
5657
6673
|
usage: "ez db sql <statement>",
|
|
@@ -5693,7 +6709,7 @@ export const COMMANDS = [
|
|
|
5693
6709
|
{
|
|
5694
6710
|
usage:
|
|
5695
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>]",
|
|
5696
|
-
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
|
|
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)",
|
|
5697
6713
|
},
|
|
5698
6714
|
{
|
|
5699
6715
|
usage:
|
|
@@ -5758,7 +6774,7 @@ export const COMMANDS = [
|
|
|
5758
6774
|
function formatHelp(commands) {
|
|
5759
6775
|
const width = Math.max(...commands.map((c) => c.usage.length));
|
|
5760
6776
|
const lines = commands.map((c) => ` ${c.usage.padEnd(width)} ${c.help}`);
|
|
5761
|
-
return `Commands (add --json to any of them for machine-readable output
|
|
6777
|
+
return `Commands (add --json to any of them for machine-readable output):\n${lines.join("\n")}`;
|
|
5762
6778
|
}
|
|
5763
6779
|
|
|
5764
6780
|
/** @type {typeof import("./commands.d.mts").HELP} */
|
|
@@ -5836,7 +6852,7 @@ export const pinnedGlobalPath = (path) =>
|
|
|
5836
6852
|
path !== TYPES_FILE;
|
|
5837
6853
|
|
|
5838
6854
|
/**
|
|
5839
|
-
* A Global push's two kinds of change (docs/adr/
|
|
6855
|
+
* A Global push's two kinds of change (docs/adr/0224): Live ones took effect for every deployed Site at once;
|
|
5840
6856
|
* the rest reach each Site at its next Preview or Deploy.
|
|
5841
6857
|
* @param {import("./types.d.mts").PushResult} result
|
|
5842
6858
|
*/
|
|
@@ -5918,7 +6934,7 @@ function liveLines(result) {
|
|
|
5918
6934
|
}
|
|
5919
6935
|
|
|
5920
6936
|
/**
|
|
5921
|
-
* What changed access rules do to Members' rows (docs/adr/
|
|
6937
|
+
* What changed access rules do to Members' rows (docs/adr/0225), Member by Member, the first 20 per rule.
|
|
5922
6938
|
* @param {import("./types.d.mts").PushResult} result
|
|
5923
6939
|
*/
|
|
5924
6940
|
function reportLines(result) {
|
|
@@ -5947,7 +6963,7 @@ function reportLines(result) {
|
|
|
5947
6963
|
|
|
5948
6964
|
/**
|
|
5949
6965
|
* A Site's Check and Preview build with the Global Working Copy beside it, unpushed edits included (ADR
|
|
5950
|
-
*
|
|
6966
|
+
* 0217); a failure in global/ says so, since the edit may be another agent's in a shared folder.
|
|
5951
6967
|
* @param {Record<string, string> | undefined} globalCopy @param {import("./commands.d.mts").Diagnostic[]} diagnostics
|
|
5952
6968
|
*/
|
|
5953
6969
|
const globalCopyNote = (globalCopy, diagnostics) =>
|
|
@@ -5958,7 +6974,7 @@ const globalCopyNote = (globalCopy, diagnostics) =>
|
|
|
5958
6974
|
const versionLine = (v) => `v${v.n}${v.by ? ` by ${v.by}` : ""}${v.at ? ` ${ago(v.at)}` : ""}`;
|
|
5959
6975
|
|
|
5960
6976
|
/**
|
|
5961
|
-
* After a write to db/schema.sql or a workflow (docs/adr/
|
|
6977
|
+
* After a write to db/schema.sql or a workflow (docs/adr/0227): rewrite db/types.d.ts when the declaration
|
|
5962
6978
|
* parses (a parse error is reported by check and push, not here).
|
|
5963
6979
|
* @param {Workspace} ws @param {string} path
|
|
5964
6980
|
*/
|
|
@@ -5973,7 +6989,7 @@ async function regenerateTypes(ws, path) {
|
|
|
5973
6989
|
}
|
|
5974
6990
|
|
|
5975
6991
|
/**
|
|
5976
|
-
* Before a check or push (docs/adr/
|
|
6992
|
+
* Before a check or push (docs/adr/0215): rewrite CONTEXT.md's file inventory when it has text and its block
|
|
5977
6993
|
* is missing or stale (an empty CONTEXT.md is the \`context\` error's, not this).
|
|
5978
6994
|
* @param {Workspace} ws
|
|
5979
6995
|
*/
|
|
@@ -5987,28 +7003,24 @@ async function regenerateInventory(ws) {
|
|
|
5987
7003
|
|
|
5988
7004
|
/**
|
|
5989
7005
|
* `ez status`'s schema lines: the Global Working Copy's changes relative to the live App Database.
|
|
5990
|
-
* @param {Workspace} ws @param {Record<string,string>} files @param {string} instance
|
|
7006
|
+
* @param {Workspace} ws @param {Record<string,string>} files @param {string} instance
|
|
5991
7007
|
*/
|
|
5992
|
-
async function schemaStatus(ws, files, instance
|
|
7008
|
+
async function schemaStatus(ws, files, instance) {
|
|
5993
7009
|
if (!(SCHEMA_FILE in files)) return null;
|
|
5994
7010
|
const decl = parseGlobalSchema(files[SCHEMA_FILE]);
|
|
5995
7011
|
if ("error" in decl) {
|
|
5996
7012
|
const message = `${SCHEMA_FILE} line ${decl.line}: ${decl.error}`;
|
|
5997
7013
|
return { lines: [`schema: ${message}`], data: { ok: false, error: message } };
|
|
5998
7014
|
}
|
|
5999
|
-
const plan = planSchema(await ws.dbSchema(), decl, instance
|
|
7015
|
+
const plan = planSchema(await ws.dbSchema(), decl, instance);
|
|
6000
7016
|
if ("error" in plan)
|
|
6001
7017
|
return { lines: [`schema: ${plan.error}`], data: { ok: false, error: plan.error } };
|
|
6002
7018
|
const { created, added, indexed } = plan.summary;
|
|
6003
7019
|
const lines = [];
|
|
6004
7020
|
if (plan.conflicts.length > 0) {
|
|
6005
|
-
lines.push(
|
|
6006
|
-
"schema: conflicts with other sites; deploy would be refused until they change their declaration",
|
|
6007
|
-
);
|
|
7021
|
+
lines.push("schema: conflicts with the App Database; deploy would be refused");
|
|
6008
7022
|
for (const c of plan.conflicts)
|
|
6009
|
-
lines.push(
|
|
6010
|
-
` ${c.table}.${c.column}: you declare ${c.mine}; ${c.site ? `site "${c.site}" declares ${c.theirs}` : `it is ${c.theirs}`}`,
|
|
6011
|
-
);
|
|
7023
|
+
lines.push(` ${c.table}.${c.column}: declared ${c.mine}; it is ${c.theirs}`);
|
|
6012
7024
|
} else if (created.length + added.length + indexed.length === 0) {
|
|
6013
7025
|
lines.push("schema: up to date");
|
|
6014
7026
|
} else {
|
|
@@ -6022,14 +7034,14 @@ async function schemaStatus(ws, files, instance, siteId) {
|
|
|
6022
7034
|
}
|
|
6023
7035
|
|
|
6024
7036
|
/**
|
|
6025
|
-
* What the Site's next deploy brings in from the Global Workspace (docs/adr/
|
|
7037
|
+
* What the Site's next deploy brings in from the Global Workspace (docs/adr/0211): the pushed Global files that
|
|
6026
7038
|
* changed since the Version its live app was built with, as the Host recorded that deploy. A deploy builds the
|
|
6027
7039
|
* pushed Global, so unpushed Global changes are not among them.
|
|
6028
7040
|
* @type {typeof import("./commands.d.mts").globalSinceDeploy}
|
|
6029
7041
|
*/
|
|
6030
7042
|
export async function globalSinceDeploy(site, global) {
|
|
6031
7043
|
const deployed = site.deployedGlobal;
|
|
6032
|
-
if (site.deployedAt === null ||
|
|
7044
|
+
if (site.deployedAt === null || deployed === null) return null;
|
|
6033
7045
|
const newest = (await global.remoteStatus()).version.n;
|
|
6034
7046
|
if (newest <= deployed)
|
|
6035
7047
|
return { deployed, current: newest, paths: { added: [], changed: [], removed: [] } };
|
|
@@ -6082,7 +7094,7 @@ export function describeCommand(argv) {
|
|
|
6082
7094
|
const [cmd, a, b] = argv;
|
|
6083
7095
|
switch (cmd) {
|
|
6084
7096
|
case "function":
|
|
6085
|
-
return `Called function ${b ?? ""}`.trim();
|
|
7097
|
+
return a === "ls" ? "Listed the functions" : `Called function ${b ?? ""}`.trim();
|
|
6086
7098
|
case "schedule":
|
|
6087
7099
|
return a === "run"
|
|
6088
7100
|
? `Ran schedule ${b ?? ""}`.trim()
|
|
@@ -6113,7 +7125,7 @@ export function describeCommand(argv) {
|
|
|
6113
7125
|
: "Formatted the working copy";
|
|
6114
7126
|
case "preview":
|
|
6115
7127
|
if (a === "ls") return "Listed the previews";
|
|
6116
|
-
if (a === "delete"
|
|
7128
|
+
if (a === "delete") return `Deleted the ${b ?? ""} preview`.trim();
|
|
6117
7129
|
return "Previewed the working copy";
|
|
6118
7130
|
case "link":
|
|
6119
7131
|
if (a !== "--preview") return "Made a sign-in link to the app";
|
|
@@ -6127,7 +7139,6 @@ export function describeCommand(argv) {
|
|
|
6127
7139
|
case "edit":
|
|
6128
7140
|
return `Edited ${a ?? ""}`.trim();
|
|
6129
7141
|
case "delete":
|
|
6130
|
-
case "rm":
|
|
6131
7142
|
return `Deleted ${a ?? ""}`.trim();
|
|
6132
7143
|
case "mv":
|
|
6133
7144
|
return `Renamed ${a ?? ""} to ${b ?? ""}`.trim();
|
|
@@ -6140,13 +7151,13 @@ export function describeCommand(argv) {
|
|
|
6140
7151
|
case "site":
|
|
6141
7152
|
if (a === "ls") return "Listed the instance's sites";
|
|
6142
7153
|
if (a === "create") return `Created site ${b ?? ""}`.trim();
|
|
6143
|
-
if (a === "archive"
|
|
7154
|
+
if (a === "archive") return `Archived site ${b ?? ""}`.trim();
|
|
6144
7155
|
if (a === "access") {
|
|
6145
7156
|
const [, , verb, , who] = argv;
|
|
6146
7157
|
if (verb === "restrict") return "Restricted the site";
|
|
6147
7158
|
if (verb === "open") return "Opened the site to the instance";
|
|
6148
7159
|
if (verb === "add") return `Allowed ${who ?? ""}`.trim();
|
|
6149
|
-
if (verb === "remove"
|
|
7160
|
+
if (verb === "remove") return `Disallowed ${who ?? ""}`.trim();
|
|
6150
7161
|
return "Read who may open the site";
|
|
6151
7162
|
}
|
|
6152
7163
|
return `Ran ez ${argv.join(" ")}`.trim();
|
|
@@ -6155,7 +7166,7 @@ export function describeCommand(argv) {
|
|
|
6155
7166
|
case "builder":
|
|
6156
7167
|
if (a === "add") return `Invited ${b ?? ""}`.trim();
|
|
6157
7168
|
if (a === "set-role") return `Changed ${b ?? ""}'s role`.trim();
|
|
6158
|
-
if (a === "remove"
|
|
7169
|
+
if (a === "remove") return `Removed ${b ?? ""}`.trim();
|
|
6159
7170
|
return `Ran ez ${argv.join(" ")}`.trim();
|
|
6160
7171
|
case "users":
|
|
6161
7172
|
return "Listed the app members";
|
|
@@ -6163,7 +7174,7 @@ export function describeCommand(argv) {
|
|
|
6163
7174
|
if (a === "add") return `Added ${b ?? ""}`.trim();
|
|
6164
7175
|
if (a === "block") return `Blocked ${b ?? ""}`.trim();
|
|
6165
7176
|
if (a === "unblock") return `Unblocked ${b ?? ""}`.trim();
|
|
6166
|
-
if (a === "remove"
|
|
7177
|
+
if (a === "remove") return `Removed ${b ?? ""}`.trim();
|
|
6167
7178
|
return `Ran ez ${argv.join(" ")}`.trim();
|
|
6168
7179
|
case "audit":
|
|
6169
7180
|
return "Read the instance's audit trail";
|
|
@@ -6194,7 +7205,6 @@ export function describeCommand(argv) {
|
|
|
6194
7205
|
: "Listed the support requests";
|
|
6195
7206
|
case "asset":
|
|
6196
7207
|
if (a === "add") return `Uploaded asset ${b ?? ""}`.trim();
|
|
6197
|
-
if (a === "delete" || a === "rm") return `Deleted asset ${b ?? ""}`.trim();
|
|
6198
7208
|
return "Listed the instance's assets";
|
|
6199
7209
|
case "db":
|
|
6200
7210
|
if (a === "tables") return "Listed the app database's tables";
|
|
@@ -6258,35 +7268,6 @@ export async function runCommand(ws, argv, stdin) {
|
|
|
6258
7268
|
: text;
|
|
6259
7269
|
}
|
|
6260
7270
|
|
|
6261
|
-
const MISSING_EXPORT_RE =
|
|
6262
|
-
/^TS(?:2305|2724): (?:Module )?'"(@ezship\/react(?:\/server|\/local)?)"' has no exported member (?:named )?'([\w$]+)'/;
|
|
6263
|
-
|
|
6264
|
-
/**
|
|
6265
|
-
* The Host's Builder says the Framework lacks a name this client's editor declarations export: the Host runs
|
|
6266
|
-
* an older Framework than this \`ez\` (docs/adr/0078). Says so on that diagnostic instead of leaving a Builder
|
|
6267
|
-
* to work around an editor and a checker that disagree.
|
|
6268
|
-
* @param {import("./commands.d.mts").Workspace} ws
|
|
6269
|
-
*/
|
|
6270
|
-
const noteSkew =
|
|
6271
|
-
(ws) =>
|
|
6272
|
-
/** @param {{ diagnostics: import("./commands.d.mts").Diagnostic[] }} result */
|
|
6273
|
-
async (result) => {
|
|
6274
|
-
const missing = result.diagnostics.filter((d) => MISSING_EXPORT_RE.test(d.message));
|
|
6275
|
-
if (!missing.length || !ws.editorExports) return result;
|
|
6276
|
-
/** @type {Record<string, string[]>} */
|
|
6277
|
-
const exported = await ws.editorExports().catch(() => ({}));
|
|
6278
|
-
return {
|
|
6279
|
-
diagnostics: result.diagnostics.map((d) => {
|
|
6280
|
-
const m = MISSING_EXPORT_RE.exec(d.message);
|
|
6281
|
-
if (!m || !exported[m[1]]?.includes(m[2])) return d;
|
|
6282
|
-
return {
|
|
6283
|
-
...d,
|
|
6284
|
-
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.`,
|
|
6285
|
-
};
|
|
6286
|
-
}),
|
|
6287
|
-
};
|
|
6288
|
-
};
|
|
6289
|
-
|
|
6290
7271
|
/**
|
|
6291
7272
|
* A command that failed with a result: `message` is what to print, `data` what `--json` prints instead. The
|
|
6292
7273
|
* command still fails (`ez` exits non-zero), and under --json the message is the JSON.
|
|
@@ -6476,7 +7457,22 @@ async function execute(ws, argv, stdin) {
|
|
|
6476
7457
|
return out(renderLine(row), row);
|
|
6477
7458
|
}
|
|
6478
7459
|
case "function": {
|
|
6479
|
-
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
|
+
}
|
|
6480
7476
|
if (
|
|
6481
7477
|
args[0] !== "call" ||
|
|
6482
7478
|
!FUNCTION_NAME_RE.test(args[1] ?? "") ||
|
|
@@ -6490,7 +7486,18 @@ async function execute(ws, argv, stdin) {
|
|
|
6490
7486
|
} catch {
|
|
6491
7487
|
throw usage(`${syntax}: input must be JSON`);
|
|
6492
7488
|
}
|
|
6493
|
-
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
|
+
});
|
|
6494
7501
|
return out(JSON.stringify(result.result, null, 2), result);
|
|
6495
7502
|
}
|
|
6496
7503
|
case "schedule": {
|
|
@@ -6509,7 +7516,6 @@ async function execute(ws, argv, stdin) {
|
|
|
6509
7516
|
s.name,
|
|
6510
7517
|
s.cron,
|
|
6511
7518
|
s.job,
|
|
6512
|
-
// An older Host answers no `paused`.
|
|
6513
7519
|
s.paused ? `paused by ${s.paused.by}` : `next ${utcMinute(s.next)}`,
|
|
6514
7520
|
s.last ? `last ${s.last.status} ${utcMinute(s.last.due)}` : "never run",
|
|
6515
7521
|
].join(" "),
|
|
@@ -6579,9 +7585,9 @@ async function execute(ws, argv, stdin) {
|
|
|
6579
7585
|
for (const p of changes.deleted) lines.push(` deleted ${p}`);
|
|
6580
7586
|
const schema = global
|
|
6581
7587
|
? null
|
|
6582
|
-
: await schemaStatus(ws, (await ws.globalFiles?.()) ?? {}, remote.instance
|
|
7588
|
+
: await schemaStatus(ws, (await ws.globalFiles?.()) ?? {}, remote.instance);
|
|
6583
7589
|
if (schema) lines.push(...schema.lines);
|
|
6584
|
-
// What the deploy also brings in from the Global Workspace (docs/adr/
|
|
7590
|
+
// What the deploy also brings in from the Global Workspace (docs/adr/0211); never fails the status.
|
|
6585
7591
|
const brings = global
|
|
6586
7592
|
? null
|
|
6587
7593
|
: await (async () => {
|
|
@@ -6663,7 +7669,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6663
7669
|
throw usage('ez push [-m "<message>"] [--prune] [--force]');
|
|
6664
7670
|
const checked = messageText(message, "The message");
|
|
6665
7671
|
if ("error" in checked) throw new Error(checked.error);
|
|
6666
|
-
// --dry-run reports a Global push's Live changes (docs/adr/
|
|
7672
|
+
// --dry-run reports a Global push's Live changes (docs/adr/0224). A Site push has none, and ignoring the
|
|
6667
7673
|
// flag would push for real, so it is refused before anything is sent.
|
|
6668
7674
|
if (!global && flags.has("--dry-run"))
|
|
6669
7675
|
throw new Error(
|
|
@@ -6678,7 +7684,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6678
7684
|
for (const [p, c] of Object.entries(files))
|
|
6679
7685
|
if (c.length > MAX_FILE_BYTES)
|
|
6680
7686
|
throw new Error(`${p} is too large (max ${MAX_FILE_BYTES} bytes)`);
|
|
6681
|
-
// A Global push first checks every Site against these files (docs/adr/
|
|
7687
|
+
// A Global push first checks every Site against these files (docs/adr/0236); --force pushes regardless.
|
|
6682
7688
|
if (global && !flags.has("--force")) {
|
|
6683
7689
|
const { diagnostics } = await ws.check(files).catch((error) => {
|
|
6684
7690
|
throw new Error(
|
|
@@ -6694,7 +7700,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6694
7700
|
// A file this copy pulled and then deleted is deleted on the shared side too; --prune additionally
|
|
6695
7701
|
// deletes shared files this copy never tracked (pushed by someone else since the pull).
|
|
6696
7702
|
const deleted = localChanges(files, await ws.pulled()).deleted;
|
|
6697
|
-
// A Global push's Live changes (docs/adr/
|
|
7703
|
+
// A Global push's Live changes (docs/adr/0224): --dry-run reports them without saving,
|
|
6698
7704
|
// --acknowledge-exposure accepts rules that let Members read more, --force is an Admin's (server-checked).
|
|
6699
7705
|
/** @type {{ message?: string, dryRun?: boolean, acknowledgeExposure?: boolean, force?: boolean }} */
|
|
6700
7706
|
const options = {};
|
|
@@ -6721,9 +7727,9 @@ async function execute(ws, argv, stdin) {
|
|
|
6721
7727
|
const lines = [
|
|
6722
7728
|
`Deployed ${plural(r.files.length, "file")} at ${new Date(r.deployedAt).toLocaleString()}${r.global ? ` with global v${r.global}` : ""}.${r.appUrl ? ` ${r.appUrl}` : ""}`,
|
|
6723
7729
|
];
|
|
6724
|
-
for (const t of r.schema
|
|
6725
|
-
for (const c of r.schema
|
|
6726
|
-
for (const i of r.schema
|
|
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}`);
|
|
6727
7733
|
for (const w of r.warnings ?? []) lines.push(`warning: ${w}`);
|
|
6728
7734
|
return out(lines.join("\n"), r);
|
|
6729
7735
|
}
|
|
@@ -6731,7 +7737,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6731
7737
|
case "versions": {
|
|
6732
7738
|
const rows = await ws.listVersions();
|
|
6733
7739
|
if (rows.length === 0) return out("No versions yet. Push first.", rows);
|
|
6734
|
-
// A Site's rows say which Version Members see and which a deploy shipped before (docs/adr/
|
|
7740
|
+
// A Site's rows say which Version Members see and which a deploy shipped before (docs/adr/0211).
|
|
6735
7741
|
/** @param {Version} v */
|
|
6736
7742
|
const shipped = (v) =>
|
|
6737
7743
|
v.live ? " [live]" : v.deployedAt ? ` [deployed ${ago(v.deployedAt)}]` : "";
|
|
@@ -6749,12 +7755,10 @@ async function execute(ws, argv, stdin) {
|
|
|
6749
7755
|
await regenerateInventory(ws);
|
|
6750
7756
|
Object.assign(files, await ws.files());
|
|
6751
7757
|
const local = global ? checkGlobalStructure(files) : checkStructure(files);
|
|
6752
|
-
// A Site checks against the Global Working Copy its Preview would upload (ADR
|
|
7758
|
+
// A Site checks against the Global Working Copy its Preview would upload (ADR 0217).
|
|
6753
7759
|
const globalCopy = global || local.length > 0 ? undefined : await ws.globalFiles?.();
|
|
6754
7760
|
const { diagnostics } =
|
|
6755
|
-
local.length > 0
|
|
6756
|
-
? { diagnostics: local }
|
|
6757
|
-
: await ws.check(files, globalCopy).then(noteSkew(ws));
|
|
7761
|
+
local.length > 0 ? { diagnostics: local } : await ws.check(files, globalCopy);
|
|
6758
7762
|
const entries = checkEntries(diagnostics);
|
|
6759
7763
|
if (diagnostics.some((d) => d.severity !== 2))
|
|
6760
7764
|
throw new CommandFailure(
|
|
@@ -6767,7 +7771,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6767
7771
|
);
|
|
6768
7772
|
}
|
|
6769
7773
|
|
|
6770
|
-
// `ez format` (docs/adr/
|
|
7774
|
+
// `ez format` (docs/adr/0237): the Host formats the .ts/.tsx files and answers the ones that change; a file
|
|
6771
7775
|
// that does not parse stops it before anything is written. --check writes nothing and fails on a change.
|
|
6772
7776
|
case "format": {
|
|
6773
7777
|
if (pos.length || [...flags].some((f) => f !== "--check")) throw usage("ez format [--check]");
|
|
@@ -6795,7 +7799,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6795
7799
|
);
|
|
6796
7800
|
}
|
|
6797
7801
|
|
|
6798
|
-
// `ez preview` (docs/adr/
|
|
7802
|
+
// `ez preview` (docs/adr/0212): the working copy (or a retained Version) built on the Host and served at a
|
|
6799
7803
|
// private URL against the live data. The name defaults to the client's (`ws.previewName`: the CLI's folder,
|
|
6800
7804
|
// the studio's remembered name). A successful upload is also a check; a failed one keeps the last good build.
|
|
6801
7805
|
case "preview": {
|
|
@@ -6812,7 +7816,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6812
7816
|
else if (!args[i].startsWith("--")) words.push(args[i]);
|
|
6813
7817
|
}
|
|
6814
7818
|
const [sub, ...rest] = words;
|
|
6815
|
-
// Other Builders' Previews of this Site (docs/adr/
|
|
7819
|
+
// Other Builders' Previews of this Site (docs/adr/0211): who is changing it, never their URLs.
|
|
6816
7820
|
if (sub === "ls" && others) {
|
|
6817
7821
|
const rows = await ws.listOtherPreviews();
|
|
6818
7822
|
if (rows.length === 0) return out("No other Builder has a preview of this site.", rows);
|
|
@@ -6849,7 +7853,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6849
7853
|
throw usage("ez preview --name <name> (this client has no default preview name)");
|
|
6850
7854
|
return name;
|
|
6851
7855
|
};
|
|
6852
|
-
if (sub === "delete"
|
|
7856
|
+
if (sub === "delete") {
|
|
6853
7857
|
const name = rest[0] ?? (await defaultName());
|
|
6854
7858
|
const why = previewNameError(name);
|
|
6855
7859
|
if (why) throw new Error(why);
|
|
@@ -6880,9 +7884,9 @@ async function execute(ws, argv, stdin) {
|
|
|
6880
7884
|
});
|
|
6881
7885
|
}
|
|
6882
7886
|
const lines = [];
|
|
6883
|
-
for (const t of result.schema
|
|
6884
|
-
for (const c of result.schema
|
|
6885
|
-
for (const i of result.schema
|
|
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}`);
|
|
6886
7890
|
const from = result.source.kind === "version" ? ` (v${result.source.n})` : "";
|
|
6887
7891
|
if (result.status === "failed")
|
|
6888
7892
|
throw new Error(
|
|
@@ -6892,7 +7896,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6892
7896
|
return out(lines.join("\n"), result);
|
|
6893
7897
|
}
|
|
6894
7898
|
|
|
6895
|
-
// `ez link` (docs/adr/
|
|
7899
|
+
// `ez link` (docs/adr/0203): an address that opens the deployed app, or one of the caller's Previews (a
|
|
6896
7900
|
// bare --preview is the default name, as for `ez preview`), signed in as the caller's own Member identity.
|
|
6897
7901
|
// The token travels in the fragment; the platform's handoff page spends it once.
|
|
6898
7902
|
case "link": {
|
|
@@ -6969,8 +7973,7 @@ async function execute(ws, argv, stdin) {
|
|
|
6969
7973
|
return out(`Edited ${path}.`, { path });
|
|
6970
7974
|
}
|
|
6971
7975
|
|
|
6972
|
-
case "delete":
|
|
6973
|
-
case "rm": {
|
|
7976
|
+
case "delete": {
|
|
6974
7977
|
const [path] = pos;
|
|
6975
7978
|
if (!path) throw usage("ez delete <path>");
|
|
6976
7979
|
if (path === CONTEXT_FILE)
|
|
@@ -7026,10 +8029,6 @@ async function execute(ws, argv, stdin) {
|
|
|
7026
8029
|
const updated = await ws.updateSettings({ name });
|
|
7027
8030
|
return out(`name: ${updated.name}`, updated);
|
|
7028
8031
|
}
|
|
7029
|
-
if (field === "signup")
|
|
7030
|
-
throw new Error(
|
|
7031
|
-
"There is no sign-up mode: the deployed apps are invite-only (ez user add <email>).",
|
|
7032
|
-
);
|
|
7033
8032
|
throw usage("ez config set name <value>");
|
|
7034
8033
|
}
|
|
7035
8034
|
|
|
@@ -7050,10 +8049,6 @@ async function execute(ws, argv, stdin) {
|
|
|
7050
8049
|
const updated = await ws.updateInstance({ name });
|
|
7051
8050
|
return out(`name: ${updated.name}`, updated);
|
|
7052
8051
|
}
|
|
7053
|
-
if (field === "signup")
|
|
7054
|
-
throw new Error(
|
|
7055
|
-
"There is no sign-up mode: the deployed apps are invite-only (ez user add <email>).",
|
|
7056
|
-
);
|
|
7057
8052
|
throw usage("ez instance config set name <value>");
|
|
7058
8053
|
}
|
|
7059
8054
|
|
|
@@ -7080,7 +8075,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7080
8075
|
{ instance: inst.id, ...site },
|
|
7081
8076
|
);
|
|
7082
8077
|
}
|
|
7083
|
-
if (sub === "archive"
|
|
8078
|
+
if (sub === "archive") {
|
|
7084
8079
|
const [, id] = pos;
|
|
7085
8080
|
if (!id) throw usage("ez site archive <id>");
|
|
7086
8081
|
const inst = await ws.instanceStatus();
|
|
@@ -7096,7 +8091,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7096
8091
|
const render = (a) => {
|
|
7097
8092
|
if (!a.restricted)
|
|
7098
8093
|
return out(
|
|
7099
|
-
`open to every builder and member of the instance (run \`ez site access restrict\` to use allow-lists)${
|
|
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(", ")}` : ""}`,
|
|
7100
8095
|
a,
|
|
7101
8096
|
);
|
|
7102
8097
|
const lines = [
|
|
@@ -7109,14 +8104,14 @@ async function execute(ws, argv, stdin) {
|
|
|
7109
8104
|
for (const p of a.members) lines.push(` ${p.email}${p.name ? ` ${p.name}` : ""}`);
|
|
7110
8105
|
if (a.members.length === 0) lines.push(" (none)");
|
|
7111
8106
|
lines.push("groups (their members, implied groups included):");
|
|
7112
|
-
for (const g of a.groups
|
|
7113
|
-
if (
|
|
8107
|
+
for (const g of a.groups) lines.push(` ${g}`);
|
|
8108
|
+
if (a.groups.length === 0) lines.push(" (none)");
|
|
7114
8109
|
return out(lines.join("\n"), a);
|
|
7115
8110
|
};
|
|
7116
8111
|
if (verb === undefined) return render(await ws.siteAccess());
|
|
7117
8112
|
if (verb === "restrict") return render(await ws.setRestricted(true));
|
|
7118
8113
|
if (verb === "open") return render(await ws.setRestricted(false));
|
|
7119
|
-
if ((verb === "add" || verb === "remove"
|
|
8114
|
+
if ((verb === "add" || verb === "remove") && kind === "group" && who) {
|
|
7120
8115
|
if (!GROUP_RE.test(who))
|
|
7121
8116
|
throw new Error(
|
|
7122
8117
|
`A group name is lowercase letters, digits and -, starting with a letter (at most 40): ${who}`,
|
|
@@ -7130,7 +8125,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7130
8125
|
);
|
|
7131
8126
|
}
|
|
7132
8127
|
if (
|
|
7133
|
-
(verb === "add" || verb === "remove"
|
|
8128
|
+
(verb === "add" || verb === "remove") &&
|
|
7134
8129
|
(kind === "builder" || kind === "user") &&
|
|
7135
8130
|
who
|
|
7136
8131
|
) {
|
|
@@ -7152,7 +8147,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7152
8147
|
"ez site access [restrict|open|add builder|user <who>|add group <name>|remove builder|user <who>|remove group <name>]",
|
|
7153
8148
|
);
|
|
7154
8149
|
}
|
|
7155
|
-
throw usage("ez site <ls|create|archive|
|
|
8150
|
+
throw usage("ez site <ls|create|archive|access> ...");
|
|
7156
8151
|
}
|
|
7157
8152
|
|
|
7158
8153
|
case "builders": {
|
|
@@ -7199,7 +8194,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7199
8194
|
await ws.setBuilderRole(target.id, role);
|
|
7200
8195
|
return out(`${target.email} is now ${role}.`, { id: target.id, email: target.email, role });
|
|
7201
8196
|
}
|
|
7202
|
-
if (sub === "remove"
|
|
8197
|
+
if (sub === "remove") {
|
|
7203
8198
|
const [, who] = pos;
|
|
7204
8199
|
if (!who) throw usage("ez builder remove <who>");
|
|
7205
8200
|
const target = await resolvePerson(() => ws.listBuilders(), who, "builder");
|
|
@@ -7257,15 +8252,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7257
8252
|
row,
|
|
7258
8253
|
);
|
|
7259
8254
|
}
|
|
7260
|
-
|
|
7261
|
-
if (!name) throw usage("ez asset delete <name> [--force]");
|
|
7262
|
-
const rows = await ws.listAssets();
|
|
7263
|
-
const hit = rows.find((r) => r.name === name);
|
|
7264
|
-
if (!hit) throw new Error(`No such asset: ${name}`);
|
|
7265
|
-
await ws.deleteAsset(hit.id, flags.has("--force"));
|
|
7266
|
-
return out(`Deleted asset ${name}.`, { id: hit.id, name });
|
|
7267
|
-
}
|
|
7268
|
-
throw usage("ez asset add <name> <file> | ls | delete <name> [--force]");
|
|
8255
|
+
throw usage("ez asset add <name> <file> | ls");
|
|
7269
8256
|
}
|
|
7270
8257
|
|
|
7271
8258
|
case "users": {
|
|
@@ -7276,7 +8263,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7276
8263
|
.sort((a, b) => a.email.localeCompare(b.email))
|
|
7277
8264
|
.map(
|
|
7278
8265
|
(u) =>
|
|
7279
|
-
`${u.email} ${u.status}${u.name ? ` ${u.name}` : ""}${u.groups
|
|
8266
|
+
`${u.email} ${u.status}${u.name ? ` ${u.name}` : ""}${u.groups.length ? ` groups: ${u.groups.join(", ")}` : ""}${inviteSuffix(u)}`,
|
|
7280
8267
|
)
|
|
7281
8268
|
.join("\n"),
|
|
7282
8269
|
rows,
|
|
@@ -7311,7 +8298,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7311
8298
|
status: sub === "block" ? "blocked" : "active",
|
|
7312
8299
|
});
|
|
7313
8300
|
}
|
|
7314
|
-
if (sub === "remove"
|
|
8301
|
+
if (sub === "remove") {
|
|
7315
8302
|
const [, who] = pos;
|
|
7316
8303
|
if (!who) throw usage("ez user remove <who>");
|
|
7317
8304
|
const target = await resolvePerson(() => ws.listUsers(), who, "member");
|
|
@@ -7323,14 +8310,14 @@ async function execute(ws, argv, stdin) {
|
|
|
7323
8310
|
}
|
|
7324
8311
|
if (sub === "group") {
|
|
7325
8312
|
const [, verb, who, group] = pos;
|
|
7326
|
-
if ((verb !== "add" && verb !== "remove"
|
|
8313
|
+
if ((verb !== "add" && verb !== "remove") || !who || !group)
|
|
7327
8314
|
throw usage("ez user group add|remove <who> <group>");
|
|
7328
8315
|
if (!GROUP_RE.test(group))
|
|
7329
8316
|
throw new Error(
|
|
7330
8317
|
`A group name is lowercase letters, digits and -, starting with a letter (at most 40): ${group}`,
|
|
7331
8318
|
);
|
|
7332
8319
|
const target = await resolvePerson(() => ws.listUsers(), who, "member");
|
|
7333
|
-
const had = target.groups
|
|
8320
|
+
const had = target.groups;
|
|
7334
8321
|
const groups =
|
|
7335
8322
|
verb === "add" ? [...new Set([...had, group])].sort() : had.filter((g) => g !== group);
|
|
7336
8323
|
if (groups.length !== had.length) await ws.setUserGroups(target.id, groups);
|
|
@@ -7381,7 +8368,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7381
8368
|
}
|
|
7382
8369
|
|
|
7383
8370
|
case "integration": {
|
|
7384
|
-
// docs/adr/
|
|
8371
|
+
// docs/adr/0231, 0252: every secret (a credential's value, a basic password, an OAuth client
|
|
7385
8372
|
// secret, a secret value) arrives on stdin (piped, or the CLI's hidden prompt), never as an argument,
|
|
7386
8373
|
// and no result carries it.
|
|
7387
8374
|
const credentialSyntax =
|
|
@@ -7535,7 +8522,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7535
8522
|
if (originError) throw new Error(originError);
|
|
7536
8523
|
return { binding: { origin: new URL(origin).origin, credential }, preset };
|
|
7537
8524
|
};
|
|
7538
|
-
/** A preset's plain values, set on the binding after it (docs/adr/
|
|
8525
|
+
/** A preset's plain values, set on the binding after it (docs/adr/0231), the last answer kept. */
|
|
7539
8526
|
const presetValues = async (
|
|
7540
8527
|
/** @type {import("./commands.d.mts").OAuthPreset | null} */ preset,
|
|
7541
8528
|
/** @type {"production" | "preview"} */ bindingName,
|
|
@@ -7578,7 +8565,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7578
8565
|
const sites = given["--sites"];
|
|
7579
8566
|
if (sites !== undefined) {
|
|
7580
8567
|
const ids = sites === "all" ? "all" : sites.split(",").map((id) => id.trim());
|
|
7581
|
-
// `global` names the Global Workspace's jobs (ADR
|
|
8568
|
+
// `global` names the Global Workspace's jobs (ADR 0230).
|
|
7582
8569
|
if (
|
|
7583
8570
|
ids !== "all" &&
|
|
7584
8571
|
(!ids.length || ids.some((id) => id !== GLOBAL_ID && !isValidSiteId(id)))
|
|
@@ -7714,7 +8701,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7714
8701
|
}
|
|
7715
8702
|
|
|
7716
8703
|
case "listener": {
|
|
7717
|
-
// docs/adr/
|
|
8704
|
+
// docs/adr/0231: a secret arrives on stdin (piped, or the CLI's hidden prompt), never as an argument.
|
|
7718
8705
|
const syntax =
|
|
7719
8706
|
"ez listener list | secret <name> [--overlap <hours>] | secret <name> --remove | events <name> [--dead] | show <name> <event-id> | retry <name> <event-id>";
|
|
7720
8707
|
const [sub, name, ...extra] = pos;
|
|
@@ -7827,7 +8814,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7827
8814
|
}
|
|
7828
8815
|
|
|
7829
8816
|
case "key": {
|
|
7830
|
-
// docs/adr/
|
|
8817
|
+
// docs/adr/0232: the Instance's API Keys, each shown once, by create, and never again.
|
|
7831
8818
|
const syntax =
|
|
7832
8819
|
"ez key list | create <name> [--groups <a,b>] [--sites <all | ids>] [--expires <days>] | revoke <name>";
|
|
7833
8820
|
const VALUES = ["--groups", "--sites", "--expires"];
|
|
@@ -7920,7 +8907,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7920
8907
|
}
|
|
7921
8908
|
|
|
7922
8909
|
case "email": {
|
|
7923
|
-
// docs/adr/
|
|
8910
|
+
// docs/adr/0234: the Emails the Instance's server code sent, newest first.
|
|
7924
8911
|
const syntax =
|
|
7925
8912
|
"ez email list [--site <id>] [--status <status>] [--since <YYYY-MM-DD>] [--limit <n>] | ez email show <id> [--html]";
|
|
7926
8913
|
const [sub, ...rest] = args;
|
|
@@ -7983,7 +8970,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7983
8970
|
}
|
|
7984
8971
|
|
|
7985
8972
|
case "support": {
|
|
7986
|
-
// docs/adr/
|
|
8973
|
+
// docs/adr/0208: a request to the Host's Developers, not to this Instance's Admins.
|
|
7987
8974
|
const syntax =
|
|
7988
8975
|
"ez support open <subject> [--body <text>] | ez support list | ez support show <id>";
|
|
7989
8976
|
const [sub, ...rest] = args;
|
|
@@ -8074,11 +9061,11 @@ async function execute(ws, argv, stdin) {
|
|
|
8074
9061
|
const lines = [];
|
|
8075
9062
|
for (const t of tables) {
|
|
8076
9063
|
lines.push(
|
|
8077
|
-
`${t.name} ${plural(t.rows, "row")}
|
|
9064
|
+
`${t.name} ${plural(t.rows, "row")}${t.history ? ` the History of ${t.history} (read-only)` : ""}`,
|
|
8078
9065
|
);
|
|
8079
9066
|
for (const [c, d] of Object.entries(t.columns)) lines.push(` ${c} ${d}`);
|
|
8080
9067
|
for (const cols of t.indexes) lines.push(` index (${cols.join(", ")})`);
|
|
8081
|
-
for (const cols of t.unique
|
|
9068
|
+
for (const cols of t.unique) lines.push(` unique index (${cols.join(", ")})`);
|
|
8082
9069
|
}
|
|
8083
9070
|
return out(lines.join("\n"), tables);
|
|
8084
9071
|
}
|
|
@@ -8087,6 +9074,12 @@ async function execute(ws, argv, stdin) {
|
|
|
8087
9074
|
return out(renderSchema(schema).trimEnd(), schema);
|
|
8088
9075
|
}
|
|
8089
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
|
+
);
|
|
8090
9083
|
const statement = (pos.slice(1).join(" ") || stdin || "").trim();
|
|
8091
9084
|
if (!statement) throw usage("ez db sql <statement> (or pipe the statement on stdin)");
|
|
8092
9085
|
const r = await ws.dbSql(statement);
|