ezship 0.1.17 → 0.1.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/commands.d.mts +18 -4
- package/commands.mjs +511 -43
- package/connections.mjs +2 -0
- package/editor-types.json.gz +0 -0
- package/ez.mjs +23 -7
- package/package.json +1 -1
- package/paths.d.mts +2 -0
- package/paths.mjs +8 -0
- package/schema.d.mts +11 -2
- package/schema.mjs +17 -4
- package/types.d.mts +48 -5
package/commands.d.mts
CHANGED
|
@@ -9,6 +9,7 @@ import type {
|
|
|
9
9
|
ListenerEntry,
|
|
10
10
|
Listener,
|
|
11
11
|
ListenerEvent,
|
|
12
|
+
LocalKind,
|
|
12
13
|
ApiKey,
|
|
13
14
|
ApiKeyInput,
|
|
14
15
|
CreatedApiKey,
|
|
@@ -227,7 +228,7 @@ export interface Workspace {
|
|
|
227
228
|
deletePreview(name: string): Promise<void>;
|
|
228
229
|
/** A one-time link to the deployed app, or to the caller's Preview `preview` (docs/adr/0203). */
|
|
229
230
|
appLink(preview?: string | null): Promise<AppLink>;
|
|
230
|
-
dbSchema(): Promise<LiveSchema>;
|
|
231
|
+
dbSchema(): Promise<LiveSchema & { ruled?: string[] }>;
|
|
231
232
|
dbTables(): Promise<TableInfo[]>;
|
|
232
233
|
dbSql(statement: string): Promise<SqlResult>;
|
|
233
234
|
dbAggregate(table: string, query: AggregateQuery): Promise<DataResult<AggregateRow>>;
|
|
@@ -334,7 +335,19 @@ export function functionName(path: string): string | null;
|
|
|
334
335
|
export const LOCAL_DIR: "local/";
|
|
335
336
|
export const LOCAL_ARTIFACT: "_local/functions.json";
|
|
336
337
|
export const LOCAL_BASE_PATH: "/_ez/local";
|
|
338
|
+
export const MEMBER_SITES_PATH: "/_ez/sites";
|
|
339
|
+
export const LOCAL_SERVICE_MAX: 5;
|
|
340
|
+
export const DESKTOP_NATIVE_PACKAGES: readonly string[];
|
|
341
|
+
/** ADR 0250: the npm packages a Site's local functions import, name to exact version. */
|
|
342
|
+
export const LOCAL_PACKAGES_FILE: "local/packages.json";
|
|
343
|
+
export const LOCAL_PACKAGES_MAX: 30;
|
|
344
|
+
/** The packages of a local/packages.json that are right, and every problem with it. */
|
|
345
|
+
export function parseLocalPackages(source: string): {
|
|
346
|
+
packages: Record<string, string>;
|
|
347
|
+
errors: string[];
|
|
348
|
+
};
|
|
337
349
|
export function localFunctionName(path: string): string | null;
|
|
350
|
+
export function localKindOf(source: string): LocalKind;
|
|
338
351
|
/** Scheduled jobs (ADR 0230): the Global Workspace's jobs/<name>.ts, run by its schedules.json, never by a browser. */
|
|
339
352
|
export const JOBS_DIR: "jobs/";
|
|
340
353
|
export function jobName(path: string): string | null;
|
|
@@ -442,6 +455,7 @@ export {
|
|
|
442
455
|
ATTACHMENT_TYPES,
|
|
443
456
|
attachmentContentType,
|
|
444
457
|
DOCUMENT_BASE_PATH,
|
|
458
|
+
FIRST_SCREEN_EVENT,
|
|
445
459
|
FUNCTION_BASE_PATH,
|
|
446
460
|
LIVE_STREAM_PATH,
|
|
447
461
|
LIVE_VERSIONS_PATH,
|
|
@@ -630,8 +644,8 @@ export function hashContent(s: string): string;
|
|
|
630
644
|
export function localChanges(files: Record<string, string>, pulled: Pulled | null): Changes;
|
|
631
645
|
/**
|
|
632
646
|
* Whether a change to this Global Workspace file reaches a deployed Site only at its next Preview or Deploy
|
|
633
|
-
* (docs/adr/0224): false for the Live-only files (session.ts, schedules.json,
|
|
634
|
-
* built from (CONTEXT.md, docs/, the generated db/types.d.ts).
|
|
647
|
+
* (docs/adr/0224): false for the Live-only files (db/access.sql, rules/, workflows/, session.ts, schedules.json,
|
|
648
|
+
* jobs/) and the files no app is built from (CONTEXT.md, docs/, the generated db/types.d.ts).
|
|
635
649
|
*/
|
|
636
650
|
export function pinnedGlobalPath(path: string): boolean;
|
|
637
651
|
/**
|
|
@@ -656,7 +670,7 @@ export const HELP: string;
|
|
|
656
670
|
export const INSTRUCTIONS: string;
|
|
657
671
|
/** `ez help <topic>`, in index order. */
|
|
658
672
|
export const HELP_TOPICS: readonly { name: string; summary: string; text: () => string }[];
|
|
659
|
-
/** `ez help [<topic> | all]`'s text; null
|
|
673
|
+
/** `ez help [<topic> | <command> | all]`'s text (a command's usage lines); null when neither names one. */
|
|
660
674
|
export function helpText(topic?: string): string | null;
|
|
661
675
|
/** A complete example of `ez help recipes`; the Pipeline's tests build each against the starter Global. */
|
|
662
676
|
export type Recipe = {
|
package/commands.mjs
CHANGED
|
@@ -37,6 +37,7 @@ export {
|
|
|
37
37
|
ATTACHMENT_TYPES,
|
|
38
38
|
attachmentContentType,
|
|
39
39
|
DOCUMENT_BASE_PATH,
|
|
40
|
+
FIRST_SCREEN_EVENT,
|
|
40
41
|
FUNCTION_BASE_PATH,
|
|
41
42
|
LIVE_STREAM_PATH,
|
|
42
43
|
LIVE_VERSIONS_PATH,
|
|
@@ -167,11 +168,113 @@ export const LOCAL_DIR = "local/";
|
|
|
167
168
|
export const LOCAL_ARTIFACT = "_local/functions.json";
|
|
168
169
|
/** @type {typeof import("./commands.d.mts").LOCAL_BASE_PATH} */
|
|
169
170
|
export const LOCAL_BASE_PATH = "/_ez/local";
|
|
171
|
+
/**
|
|
172
|
+
* On an Instance's app origin, the Sites the signed-in Member may open with when each was deployed (ADR 0250):
|
|
173
|
+
* how the Desktop finds the local services to start.
|
|
174
|
+
* @type {typeof import("./commands.d.mts").MEMBER_SITES_PATH}
|
|
175
|
+
*/
|
|
176
|
+
export const MEMBER_SITES_PATH = "/_ez/sites";
|
|
177
|
+
/**
|
|
178
|
+
* The most `localService` files a Site may hold (ADR 0250).
|
|
179
|
+
* @type {typeof import("./commands.d.mts").LOCAL_SERVICE_MAX}
|
|
180
|
+
*/
|
|
181
|
+
export const LOCAL_SERVICE_MAX = 5;
|
|
182
|
+
/**
|
|
183
|
+
* Native packages ezship Desktop ships, built for it, which local functions import by name without listing
|
|
184
|
+
* them (ADR 0250). The list grows by Desktop release.
|
|
185
|
+
* @type {typeof import("./commands.d.mts").DESKTOP_NATIVE_PACKAGES}
|
|
186
|
+
*/
|
|
187
|
+
export const DESKTOP_NATIVE_PACKAGES = Object.freeze(["serialport"]);
|
|
188
|
+
/**
|
|
189
|
+
* The optional Site file of npm packages its local functions import (ADR 0250): a JSON object of package name
|
|
190
|
+
* to exact version, which the Pipeline installs and bundles into the local artifact.
|
|
191
|
+
* @type {typeof import("./commands.d.mts").LOCAL_PACKAGES_FILE}
|
|
192
|
+
*/
|
|
193
|
+
export const LOCAL_PACKAGES_FILE = "local/packages.json";
|
|
194
|
+
/** @type {typeof import("./commands.d.mts").LOCAL_PACKAGES_MAX} */
|
|
195
|
+
export const LOCAL_PACKAGES_MAX = 30;
|
|
196
|
+
/** An npm package name as the registry takes a new one: lowercase, optionally scoped, at most 214 characters. */
|
|
197
|
+
const NPM_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
|
|
198
|
+
/** One semantic version, nothing that resolves to several: no range, tag, URL, git or file spec. */
|
|
199
|
+
const EXACT_VERSION_RE =
|
|
200
|
+
/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
|
|
201
|
+
/**
|
|
202
|
+
* The package a bare specifier imports ("mqtt/lib/x" is mqtt, "@scope/name/x" is @scope/name), or null for a
|
|
203
|
+
* relative, `global/`, `node:` or malformed one.
|
|
204
|
+
* @param {string} specifier
|
|
205
|
+
*/
|
|
206
|
+
function packageOf(specifier) {
|
|
207
|
+
if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("global/"))
|
|
208
|
+
return null;
|
|
209
|
+
if (specifier.startsWith("node:")) return null;
|
|
210
|
+
const parts = specifier.split("/");
|
|
211
|
+
const name = specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? "");
|
|
212
|
+
return NPM_NAME_RE.test(name) ? name : null;
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* The packages a local/packages.json lists and every problem with it (ADR 0250); `packages` holds the entries
|
|
216
|
+
* that are right, so an import of one of them is not refused for another entry's mistake.
|
|
217
|
+
* @type {typeof import("./commands.d.mts").parseLocalPackages}
|
|
218
|
+
*/
|
|
219
|
+
export function parseLocalPackages(source) {
|
|
220
|
+
const shape = `${LOCAL_PACKAGES_FILE} is a JSON object of npm package names and exact versions: { "mqtt": "5.10.1" }.`;
|
|
221
|
+
let parsed;
|
|
222
|
+
try {
|
|
223
|
+
parsed = JSON.parse(source);
|
|
224
|
+
} catch (error) {
|
|
225
|
+
const why = error instanceof Error ? error.message : String(error);
|
|
226
|
+
return { packages: {}, errors: [`${LOCAL_PACKAGES_FILE} is not JSON: ${why}`] };
|
|
227
|
+
}
|
|
228
|
+
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
|
|
229
|
+
return { packages: {}, errors: [shape] };
|
|
230
|
+
const entries = Object.entries(parsed);
|
|
231
|
+
if (entries.length > LOCAL_PACKAGES_MAX)
|
|
232
|
+
return {
|
|
233
|
+
packages: {},
|
|
234
|
+
errors: [
|
|
235
|
+
`${LOCAL_PACKAGES_FILE} lists ${entries.length} packages; a Site lists at most ${LOCAL_PACKAGES_MAX}.`,
|
|
236
|
+
],
|
|
237
|
+
};
|
|
238
|
+
/** @type {Record<string, string>} */
|
|
239
|
+
const packages = {};
|
|
240
|
+
/** @type {string[]} */
|
|
241
|
+
const errors = [];
|
|
242
|
+
for (const [name, version] of entries) {
|
|
243
|
+
const label = `${LOCAL_PACKAGES_FILE}: "${name}"`;
|
|
244
|
+
if (name.length > 214 || !NPM_NAME_RE.test(name))
|
|
245
|
+
errors.push(
|
|
246
|
+
`${label} is not an npm package name (lowercase, as npm shows it: "mqtt", "@scope/name").`,
|
|
247
|
+
);
|
|
248
|
+
else if (name.startsWith("@ezship/"))
|
|
249
|
+
errors.push(`${label}: the Framework comes with every Site; import @ezship/react/local.`);
|
|
250
|
+
else if (DESKTOP_NATIVE_PACKAGES.includes(name))
|
|
251
|
+
errors.push(`${label}: ezship Desktop ships it; import it without listing it.`);
|
|
252
|
+
else if (NODE_BUILTINS.has(name))
|
|
253
|
+
errors.push(`${label} is a Node built-in's name; import node:${name} without listing it.`);
|
|
254
|
+
else if (typeof version !== "string" || !EXACT_VERSION_RE.test(version))
|
|
255
|
+
errors.push(
|
|
256
|
+
`${label}: ${JSON.stringify(version)} is not an exact version; write the one version to install ("5.10.1"), never a range, tag, URL or path.`,
|
|
257
|
+
);
|
|
258
|
+
else packages[name] = version;
|
|
259
|
+
}
|
|
260
|
+
return { packages, errors };
|
|
261
|
+
}
|
|
170
262
|
/** @type {typeof import("./commands.d.mts").localFunctionName} */
|
|
171
263
|
export function localFunctionName(path) {
|
|
172
264
|
const match = /^local\/([a-z][A-Za-z0-9]{0,63})\.ts$/.exec(path);
|
|
173
265
|
return match ? match[1] : null;
|
|
174
266
|
}
|
|
267
|
+
const LOCAL_FACTORY_RE =
|
|
268
|
+
/\bexport\s+default\s+(localFunction|localStream|localService)\s*(?:<[^()]*>)?\s*\(/;
|
|
269
|
+
/**
|
|
270
|
+
* The kind of local file `source` is (ADR 0250), by the factory it default-exports; the Rules make that
|
|
271
|
+
* export one call of one of the three factories, so anything else reads as a function.
|
|
272
|
+
* @type {typeof import("./commands.d.mts").localKindOf}
|
|
273
|
+
*/
|
|
274
|
+
export function localKindOf(source) {
|
|
275
|
+
const factory = LOCAL_FACTORY_RE.exec(source)?.[1];
|
|
276
|
+
return factory === "localStream" ? "stream" : factory === "localService" ? "service" : "function";
|
|
277
|
+
}
|
|
175
278
|
/**
|
|
176
279
|
* jobs/<name>.ts in the Global Workspace: the Instance's scheduled jobs (ADR 0230), server code no browser
|
|
177
280
|
* can call; schedules.json runs them.
|
|
@@ -702,7 +805,7 @@ export function isValidFilePath(path) {
|
|
|
702
805
|
const INVALID_PATH = (p) =>
|
|
703
806
|
`Invalid path: ${p}. Use relative paths like components/Hello.tsx (no leading slash, no ..).`;
|
|
704
807
|
|
|
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.`;
|
|
808
|
+
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 ${LOCAL_PACKAGES_FILE} (npm packages for local functions), optional ${PAGE_FILE} (the browser icon) and optional ${STYLE_FILE}. Schema, generated types and scheduled jobs belong to the Global Workspace.`;
|
|
706
809
|
|
|
707
810
|
/**
|
|
708
811
|
* Why required context is invalid, or null. Content quality is guided by the instructions, not parsed.
|
|
@@ -821,7 +924,7 @@ const hookPathError = (/** @type {string} */ path, /** @type {string} */ shape)
|
|
|
821
924
|
export function siteFileError(path) {
|
|
822
925
|
if (!isValidFilePath(path)) return INVALID_PATH(path);
|
|
823
926
|
if (functionName(path) || localFunctionName(path) || listenerName(path)) return null;
|
|
824
|
-
if (path === LISTENERS_FILE || path === PAGE_FILE) return null;
|
|
927
|
+
if (path === LISTENERS_FILE || path === PAGE_FILE || path === LOCAL_PACKAGES_FILE) return null;
|
|
825
928
|
if (path.startsWith(LISTENERS_DIR)) {
|
|
826
929
|
if (path.slice(LISTENERS_DIR.length).includes("/"))
|
|
827
930
|
return `${path}: listeners/ has no subfolders. ${SITE_SHAPE}`;
|
|
@@ -1329,9 +1432,9 @@ a.card:hover { background: var(--hover); border-color: var(--line-strong); }
|
|
|
1329
1432
|
.tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--line); overflow-x: auto; scrollbar-width: none; }
|
|
1330
1433
|
.tabs .tab { position: relative; display: inline-flex; align-items: center; gap: 6px; min-height: 38px; padding: 0 12px; margin-bottom: -1px; border: 0; border-bottom: 2px solid transparent; background: none; color: var(--muted); font-weight: 500; text-decoration: none; white-space: nowrap; cursor: pointer; }
|
|
1331
1434
|
.tabs .tab:hover { color: var(--text); }
|
|
1332
|
-
.tabs .tab[aria-current] { color: var(--text); border-bottom-color: var(--primary); }
|
|
1435
|
+
.tabs .tab:is(button[aria-current], [aria-current="page"]) { color: var(--text); border-bottom-color: var(--primary); }
|
|
1333
1436
|
.tabs .count { min-width: 20px; padding: 0 6px; border-radius: 999px; background: var(--surface-2); color: var(--muted); font-size: 0.75rem; line-height: 18px; text-align: center; font-variant-numeric: tabular-nums; }
|
|
1334
|
-
.tabs .tab[aria-current] .count { background: var(--primary-soft); color: var(--primary); }
|
|
1437
|
+
.tabs .tab:is(button[aria-current], [aria-current="page"]) .count { background: var(--primary-soft); color: var(--primary); }
|
|
1335
1438
|
|
|
1336
1439
|
/* ---- FilterChips ---- */
|
|
1337
1440
|
.chips { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
|
|
@@ -2165,8 +2268,9 @@ export default function StateBadge({
|
|
|
2165
2268
|
"components/Tabs.tsx": `import { Link } from "@ezship/react";
|
|
2166
2269
|
|
|
2167
2270
|
/**
|
|
2168
|
-
* A row of tabs. A tab with \`to\` is a link
|
|
2169
|
-
* buttons, current when their \`value\` is \`value\`, and call \`onChange\`.
|
|
2271
|
+
* A row of tabs. A tab with \`to\` is a link, current on exactly its route and query (\`/?status=open\`; \`/\` is
|
|
2272
|
+
* the unfiltered one); the others are buttons, current when their \`value\` is \`value\`, and call \`onChange\`.
|
|
2273
|
+
* \`count\` draws a number beside it.
|
|
2170
2274
|
*/
|
|
2171
2275
|
export default function Tabs({
|
|
2172
2276
|
tabs,
|
|
@@ -2753,6 +2857,7 @@ function resolveRelative(from, specifier) {
|
|
|
2753
2857
|
return parts.join("/");
|
|
2754
2858
|
}
|
|
2755
2859
|
|
|
2860
|
+
const LOCAL_IMPORT_SHAPE = `local functions import @ezship/react/local, node:* built-ins, the packages ${LOCAL_PACKAGES_FILE} lists, ${DESKTOP_NATIVE_PACKAGES.join(", ")}, constants, sibling local functions, ../functions/<name> for context.call, and type-only global/db/types.`;
|
|
2756
2861
|
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
2862
|
/**
|
|
2758
2863
|
* A component of the Instance's Global Workspace, by its short name or by its path (`global/components/<Name>`,
|
|
@@ -2785,10 +2890,19 @@ export function importError(path, specifier, typeOnly, files) {
|
|
|
2785
2890
|
if (specifier.startsWith("node:")) return null;
|
|
2786
2891
|
if (NODE_BUILTINS.has(specifier.split("/")[0]))
|
|
2787
2892
|
return `"${specifier}": write Node built-ins with the node: prefix (node:${specifier}).`;
|
|
2893
|
+
if (DESKTOP_NATIVE_PACKAGES.includes(specifier)) return null;
|
|
2894
|
+
// A package local/packages.json lists, or one of its files (ADR 0250).
|
|
2895
|
+
const listed = specifier.startsWith("@ezship/") ? null : packageOf(specifier);
|
|
2896
|
+
if (listed !== null)
|
|
2897
|
+
return Object.hasOwn(parseLocalPackages(files[LOCAL_PACKAGES_FILE] ?? "{}").packages, listed)
|
|
2898
|
+
? null
|
|
2899
|
+
: `"${specifier}": list ${listed} in ${LOCAL_PACKAGES_FILE} with an exact version ({ "${listed}": "1.2.3" }) to import it.`;
|
|
2788
2900
|
const target = resolveRelative(path, specifier);
|
|
2789
2901
|
if (target === "constants") return null;
|
|
2790
2902
|
if (target && localFunctionName(target + ".ts") && target + ".ts" in files) return null;
|
|
2791
|
-
|
|
2903
|
+
// The Site's server functions, for context.call (ADR 0250).
|
|
2904
|
+
if (target && functionName(target + ".ts") && target + ".ts" in files) return null;
|
|
2905
|
+
return `${specifier}: ${LOCAL_IMPORT_SHAPE}`;
|
|
2792
2906
|
}
|
|
2793
2907
|
// A Site's own lib module (ADR 0209): a Global lib module's imports, and the constants.
|
|
2794
2908
|
if (libModuleName(path)) {
|
|
@@ -3232,11 +3346,25 @@ export function checkStructure(files) {
|
|
|
3232
3346
|
for (const error of listeners.errors) top(LISTENERS_FILE, "listeners", error);
|
|
3233
3347
|
if (PAGE_FILE in files)
|
|
3234
3348
|
for (const error of parsePage(files[PAGE_FILE]).errors) top(PAGE_FILE, "page", error);
|
|
3349
|
+
// ADR 0250: local functions' packages, checked as a Push checks them, before any install.
|
|
3350
|
+
if (LOCAL_PACKAGES_FILE in files)
|
|
3351
|
+
for (const error of parseLocalPackages(files[LOCAL_PACKAGES_FILE]).errors)
|
|
3352
|
+
top(LOCAL_PACKAGES_FILE, "local-packages", error);
|
|
3235
3353
|
for (const warning of listeners.warnings) {
|
|
3236
3354
|
top(warning.split(" ")[0] ?? LISTENERS_FILE, "listener-unlisted", warning);
|
|
3237
3355
|
const last = out[out.length - 1];
|
|
3238
3356
|
if (last) last.severity = 2;
|
|
3239
3357
|
}
|
|
3358
|
+
// ADR 0250: every running Desktop starts every service, so a Site keeps few.
|
|
3359
|
+
const services = Object.keys(files)
|
|
3360
|
+
.filter((p) => localFunctionName(p) && localKindOf(files[p] ?? "") === "service")
|
|
3361
|
+
.sort();
|
|
3362
|
+
for (const path of services.slice(LOCAL_SERVICE_MAX))
|
|
3363
|
+
top(
|
|
3364
|
+
path,
|
|
3365
|
+
"local-services",
|
|
3366
|
+
`A Site runs at most ${LOCAL_SERVICE_MAX} local services (${services.length} here). Fold ${path}'s work into another service, or make it a local function or stream.`,
|
|
3367
|
+
);
|
|
3240
3368
|
for (const [path, source] of Object.entries(files)) {
|
|
3241
3369
|
const bad = siteFileError(path);
|
|
3242
3370
|
if (bad) {
|
|
@@ -3389,7 +3517,7 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3389
3517
|
[
|
|
3390
3518
|
"function-import",
|
|
3391
3519
|
"error",
|
|
3392
|
-
"a function file importing more than its factory, z and types",
|
|
3520
|
+
"a function file importing more than its factory, z, the helpers (today, now, toDate, toEpoch, toCents, fromCents, errorMessage, WriteError) and types",
|
|
3393
3521
|
'import { serverFunction, z } from "@ezship/react/server"',
|
|
3394
3522
|
],
|
|
3395
3523
|
[
|
|
@@ -3421,6 +3549,24 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3421
3549
|
["schedules", "error", "a schedules.json problem", "follow `ez help jobs`"],
|
|
3422
3550
|
["listeners", "error", "a listeners.json problem (docs/adr/0231)", "follow `ez help jobs`"],
|
|
3423
3551
|
["page", "error", "a page.json problem (docs/adr/0209)", "follow `ez help files`"],
|
|
3552
|
+
[
|
|
3553
|
+
"local-packages",
|
|
3554
|
+
"error",
|
|
3555
|
+
`a ${LOCAL_PACKAGES_FILE} problem: not an object of exact versions, more than ${LOCAL_PACKAGES_MAX} packages, or a package that does not install or needs compiling or an install script (ADR 0250)`,
|
|
3556
|
+
"list exact versions of pure-JavaScript packages; follow `ez help local`",
|
|
3557
|
+
],
|
|
3558
|
+
[
|
|
3559
|
+
"local-services",
|
|
3560
|
+
"error",
|
|
3561
|
+
`more than ${LOCAL_SERVICE_MAX} local/ files default-export localService (ADR 0250)`,
|
|
3562
|
+
"fold the work into fewer services, or make some local functions or streams",
|
|
3563
|
+
],
|
|
3564
|
+
[
|
|
3565
|
+
"local-secret-literal",
|
|
3566
|
+
"warning",
|
|
3567
|
+
"a string in local/ that looks like a credential: a known key prefix, a PEM block, or a long random value assigned to a name such as password, secret, token or key (ADR 0250); every Member can read the local artifact",
|
|
3568
|
+
"keep the machine's secret on the machine: an environment variable, or a file under desktop.dataDir",
|
|
3569
|
+
],
|
|
3424
3570
|
[
|
|
3425
3571
|
"listener-unlisted",
|
|
3426
3572
|
"warning",
|
|
@@ -3571,7 +3717,7 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3571
3717
|
"table-cast",
|
|
3572
3718
|
"warning",
|
|
3573
3719
|
'a cast in a Table argument (name as "orders") or to Query, Insert, Update, Where or Row (docs/adr/0222)',
|
|
3574
|
-
"a Table named at run time: db.table(name) or useLive.table(name, query); otherwise a literal name and no cast",
|
|
3720
|
+
"a Table or History named at run time: db.table(name) or useLive.table(name, query); otherwise a literal name and no cast",
|
|
3575
3721
|
],
|
|
3576
3722
|
[
|
|
3577
3723
|
"query-sentinel",
|
|
@@ -3617,7 +3763,8 @@ export function helpRules() {
|
|
|
3617
3763
|
CHECK_RULES.filter((r) => r.severity === severity)
|
|
3618
3764
|
.map((r) => ` ${r.id.padEnd(width)} ${r.summary}\n ${" ".repeat(width)} fix: ${r.fix}`)
|
|
3619
3765
|
.join("\n");
|
|
3620
|
-
return `The rules \`ez check\` runs (the same ones Push, Preview and Deploy run).
|
|
3766
|
+
return `The rules \`ez check\` runs (the same ones Push, Preview and Deploy run). Table rules, the derive and guard
|
|
3767
|
+
a Table's writes run (global/rules/<table>.ts), are another thing: \`ez help db\`. Each problem names its rule id,
|
|
3621
3768
|
a file and a line, and its message says what to write instead; \`ez check --json\` prints them as
|
|
3622
3769
|
[{ file, line, column, rule, severity, message }]. No rule sends an edit to apply: make the change the
|
|
3623
3770
|
message names. Errors fail the check; warnings never do.
|
|
@@ -4583,8 +4730,8 @@ db/schema.sql as last pushed) and the live data (the one production App Database
|
|
|
4583
4730
|
not types (run ez check first). Members see nothing until ez deploy. Live data: untouched.
|
|
4584
4731
|
ez global Global: your Global files become the Global Workspace's next Version, after ez global check
|
|
4585
4732
|
push passes for it and every Site (--force skips that; Admins only). SCHEMA IS PERMANENT HERE:
|
|
4586
|
-
published Tables, columns, types, CHECK
|
|
4587
|
-
or
|
|
4733
|
+
nothing published (Tables, columns, types, CHECK lists, references, indexes) is ever renamed,
|
|
4734
|
+
removed or changed. Push runs no DDL; it refuses a definition existing rows break (duplicates under a
|
|
4588
4735
|
new unique index, values a tightened type refuses). Takes effect NOW, for every deployed Site
|
|
4589
4736
|
and Preview: column defaults, db/access.sql, rules/, workflows/, SINGLETON, EXACTLY ONE OF,
|
|
4590
4737
|
ON DELETE RESTRICT, session.ts, jobs/ and schedules.json (the push lists them under "Takes
|
|
@@ -4915,7 +5062,8 @@ ${GLOBAL_FILES}
|
|
|
4915
5062
|
From react: useState, useActionState, useTransition, startTransition, useOptimistic, useMemo, useCallback
|
|
4916
5063
|
and types. A global component is global/<Name> or, by its path, global/components/<Name>. A page
|
|
4917
5064
|
imports \`import type { Provided } from "../App"\` for App.tsx's values (ez help frame).
|
|
4918
|
-
Server functions (functions/): @ezship/react/server (serverFunction, z and
|
|
5065
|
+
Server functions (functions/): @ezship/react/server (serverFunction, z, types and the helpers today, now,
|
|
5066
|
+
toDate, toEpoch, toCents, fromCents, errorMessage, WriteError), constants, sibling
|
|
4919
5067
|
functions, ../lib/<name>, global/constants, global/lib/<name>, global/documents/<Name> and type-only
|
|
4920
5068
|
global/db/types.
|
|
4921
5069
|
Listeners: @ezship/react/server, constants, ../lib/<name>, global/constants, global/lib/<name>, type-only
|
|
@@ -4923,8 +5071,9 @@ ${GLOBAL_FILES}
|
|
|
4923
5071
|
Site lib (lib/): ${SITE_LIB_IMPORT_SHAPE}
|
|
4924
5072
|
Global jobs (global/jobs/): @ezship/react/server, global/lib/<name>, global/constants and type-only
|
|
4925
5073
|
global/db/types; nothing imports a job.
|
|
4926
|
-
Local functions (local/): @ezship/react/local, node:* built-ins,
|
|
4927
|
-
|
|
5074
|
+
Local functions (local/): @ezship/react/local, node:* built-ins, the packages ${LOCAL_PACKAGES_FILE} lists,
|
|
5075
|
+
${DESKTOP_NATIVE_PACKAGES.join(", ")}, constants, sibling local functions, ../functions/<name> (for context.call) and type-only
|
|
5076
|
+
global/db/types; UI imports ./local/<name>; server functions never import local ones.
|
|
4928
5077
|
constants.ts: nothing. Global code: ${GLOBAL_IMPORT_SHAPE}
|
|
4929
5078
|
Global lib: ${LIB_IMPORT_SHAPE}
|
|
4930
5079
|
Documents: ${DOCUMENT_IMPORT_SHAPE}
|
|
@@ -4937,6 +5086,8 @@ Routes: the page file name is the route. index.tsx is /, orders.tsx is /orders,
|
|
|
4937
5086
|
/orders/:id (useParams().id), orders.new.tsx is /orders/new. <Link to="/orders/42">, <Link to="/orders"
|
|
4938
5087
|
site="kitchen"> (another Site of the Instance), useNavigate()(path), useSites() -> [{ id, name, url, current }].
|
|
4939
5088
|
A Link to the open route has aria-current="page", to its section aria-current="true": style a[aria-current].
|
|
5089
|
+
A Link whose to names a query (/orders?state=open) is "page" only while the route's query has those values,
|
|
5090
|
+
so link tabs tell views of one route apart; /orders is then "true".
|
|
4940
5091
|
Styling: className and the Site's style.css, which loads after the Theme (global/style.css). The Theme owns
|
|
4941
5092
|
the look of every Site, with its tokens:
|
|
4942
5093
|
${THEME_TOKENS}
|
|
@@ -5204,7 +5355,7 @@ ${snippet("chart")}
|
|
|
5204
5355
|
db.insert("orders", { customer, status: "new" }); db.update("orders", id, { status: "ready" }); db.delete("orders", id)
|
|
5205
5356
|
db.update("orders", id, { status: "paid" }, { why: "Invoice paid by card" }) -> the reason lands in that write's History row
|
|
5206
5357
|
db.settings("company_settings") -> a SINGLETON Table's row or null
|
|
5207
|
-
db.table(name) / useLive.table(name, query | null) / useLive.tableCount(name, query) -> a Table named at run time (no casts)
|
|
5358
|
+
db.table(name) / useLive.table(name, query | null) / useLive.tableCount(name, query) -> a Table or a History (\`\${table}_history\`) named at run time (no casts)
|
|
5208
5359
|
db.upload("expenses", "receipt", file) -> a FileId for a FILE column (file from <input type="file">); then insert or update with it
|
|
5209
5360
|
attachment(id) -> that file's URL for <img>, <video> or a download link
|
|
5210
5361
|
useLive("actors", { where: { id: { in: actorIds } } }) -> { id, kind, name, email }[]: current names for History actor ids
|
|
@@ -5570,20 +5721,44 @@ In local/readEmpty.ts:
|
|
|
5570
5721
|
});
|
|
5571
5722
|
UI imports ./local/readEmpty (../local/readEmpty from a page) and calls readEmpty({ path }) from an event
|
|
5572
5723
|
handler, or useCall(readEmpty, { path }) -> { result, loading, error, refresh } to run it when the page opens.
|
|
5573
|
-
A local function has every Node built-in (node:fs, node:path, node:os,
|
|
5574
|
-
the Member (user), the Site (site) and desktop.dataDir, a folder the
|
|
5575
|
-
|
|
5576
|
-
|
|
5577
|
-
|
|
5578
|
-
|
|
5579
|
-
|
|
5580
|
-
|
|
5581
|
-
|
|
5582
|
-
|
|
5583
|
-
|
|
5584
|
-
|
|
5585
|
-
|
|
5586
|
-
|
|
5724
|
+
A local function runs on Node 24 or later and has every Node built-in (node:fs, node:path, node:os,
|
|
5725
|
+
node:child_process, node:net, ...), the Member (user), the Site (site) and desktop.dataDir, a folder the
|
|
5726
|
+
Desktop keeps for this Site on this computer; it has no db.
|
|
5727
|
+
Three kinds of local file, each one default export from @ezship/react/local:
|
|
5728
|
+
localFunction(inputSchema, handler) a call, answered within 60 seconds.
|
|
5729
|
+
localStream(inputSchema, async function* (context, input) { ... yield value; })
|
|
5730
|
+
a page reads it with useLocalStream(fn, input) -> { latest, values, error, done } (the last 100 values;
|
|
5731
|
+
{ keep: n } keeps n). It runs while the page that opened it is open, with no deadline.
|
|
5732
|
+
localService(async (context) => { ... })
|
|
5733
|
+
no input; the Desktop starts it when it opens the Instance, whatever page is open, restarts it with
|
|
5734
|
+
backoff when it throws or its process dies, and stops it when the Desktop closes or the Site is
|
|
5735
|
+
deployed again (a Preview's services run while that Preview is open). At most ${LOCAL_SERVICE_MAX} per Site.
|
|
5736
|
+
Every running Desktop starts its own copy: two stations with the Site each receive every message, so
|
|
5737
|
+
give what a service writes a unique key (a UNIQUE column holding the message's id).
|
|
5738
|
+
Server calls: import save from "../functions/save" and await context.call(save, input). The Desktop sends it
|
|
5739
|
+
over the signed-in Member's session, so it runs exactly as the page's call would: the Member's access, the
|
|
5740
|
+
function's validation, History naming that Member. It is the only way local code reaches the App Database.
|
|
5741
|
+
npm packages: list them in ${LOCAL_PACKAGES_FILE}, each at one exact version, at most ${LOCAL_PACKAGES_MAX}:
|
|
5742
|
+
{ "mqtt": "5.10.1", "@types/some-lib": "1.2.0" }
|
|
5743
|
+
then import { connect } from "mqtt" in a local file. The build installs them from npm (scripts never run) and
|
|
5744
|
+
bundles them into the local artifact, so the Desktop installs nothing; a listed @types/<name> types an untyped
|
|
5745
|
+
one. Pure JavaScript only: a package with a native addon (.node, binding.gyp) or an install script is refused,
|
|
5746
|
+
naming it, and optional dependencies are left out. Only local files may import them.
|
|
5747
|
+
Native packages the Desktop ships import by name, without listing: ${DESKTOP_NATIVE_PACKAGES.join(", ")} (import { SerialPort } from "serialport").
|
|
5748
|
+
[check] Local files import only @ezship/react/local (localFunction, localStream, localService, z and types),
|
|
5749
|
+
node:* built-ins (with the prefix), the packages ${LOCAL_PACKAGES_FILE} lists, ${DESKTOP_NATIVE_PACKAGES.join(", ")}, constants, sibling
|
|
5750
|
+
local functions, ../functions/<name> and type-only global/db/types. local-packages checks the list and the
|
|
5751
|
+
install; local-secret-literal warns on a string that looks like a credential.
|
|
5752
|
+
[runtime] Input, values, results and errors cross as JSON. It is arbitrary Node code, child processes included,
|
|
5753
|
+
on every Member's computer that opens the Site in ezship Desktop, and Members who share a computer share its
|
|
5754
|
+
files. In an ordinary browser, the Studio's preview included, a call or stream fails and the Framework shows a
|
|
5755
|
+
notice that the app needs ezship Desktop; useDesktop() -> { available, version } lets a page offer manual
|
|
5756
|
+
entry instead.
|
|
5757
|
+
[advice] Use local code for station configuration, caches, exports, files exchanged with programs on that
|
|
5758
|
+
computer, and devices or brokers on its network; the App Database stays the shared record. Secrets: the local
|
|
5759
|
+
artifact is served to every Member of the Site and its source is in the Version history, so a machine's secret
|
|
5760
|
+
lives on the machine, in an environment variable or a file under desktop.dataDir; local code never stores Host
|
|
5761
|
+
tokens. Test by opening the Preview URL in ezship Desktop (ez preview prints it; ez dev keeps it fresh).`;
|
|
5587
5762
|
|
|
5588
5763
|
/** `ez help documents` (ADR 0233). */
|
|
5589
5764
|
const DOCUMENTS_TOPIC = `Documents: PDFs from Global templates in \`global/documents/<Name>.tsx\` (\`ez global put documents/Invoice.tsx\`):
|
|
@@ -6461,7 +6636,8 @@ const helpIndex = () => {
|
|
|
6461
6636
|
};
|
|
6462
6637
|
|
|
6463
6638
|
/**
|
|
6464
|
-
* `ez help [<topic>]`: the onboarding, one topic, or all of them; null
|
|
6639
|
+
* `ez help [<topic> | <command>]`: the onboarding, one topic, one command's usage, or all of them; null when
|
|
6640
|
+
* neither names one.
|
|
6465
6641
|
* @type {typeof import("./commands.d.mts").helpText}
|
|
6466
6642
|
*/
|
|
6467
6643
|
export function helpText(topic) {
|
|
@@ -6473,9 +6649,46 @@ export function helpText(topic) {
|
|
|
6473
6649
|
(t) => `==== ez help ${t.name}\n\n${t.text()}`,
|
|
6474
6650
|
),
|
|
6475
6651
|
].join("\n\n");
|
|
6476
|
-
return HELP_TOPICS.find((t) => t.name === topic)?.text() ??
|
|
6652
|
+
return HELP_TOPICS.find((t) => t.name === topic)?.text() ?? commandHelp(topic);
|
|
6477
6653
|
}
|
|
6478
6654
|
|
|
6655
|
+
/**
|
|
6656
|
+
* One command's usage lines (`ez help push`, or `ez push --help`), with `ez global <command>`'s too; null
|
|
6657
|
+
* when no command has that name. A topic of the same name (`ez help db`) comes first.
|
|
6658
|
+
* @param {string} name
|
|
6659
|
+
*/
|
|
6660
|
+
function commandHelp(name) {
|
|
6661
|
+
const lines = COMMANDS.filter(isUsageOf(name));
|
|
6662
|
+
return lines.length ? formatHelp(lines) : null;
|
|
6663
|
+
}
|
|
6664
|
+
|
|
6665
|
+
/** Whether a COMMANDS line is `ez <name> ...` or `ez global <name> ...`. @param {string} name */
|
|
6666
|
+
const isUsageOf = (name) => (/** @type {{ usage: string }} */ c) => {
|
|
6667
|
+
const words = c.usage.split(/\s+/);
|
|
6668
|
+
return words[1] === name || (words[1] === "global" && words[2] === name);
|
|
6669
|
+
};
|
|
6670
|
+
/** What every command takes: the output format, the target (read before execute) and --help. */
|
|
6671
|
+
const EVERY_COMMAND_FLAGS = ["--json", "--instance", "--site", "--account", "--help"];
|
|
6672
|
+
/** Flags a command reads that its usage lines leave out. */
|
|
6673
|
+
const MORE_FLAGS = /** @type {Record<string, string[]>} */ ({
|
|
6674
|
+
// push: -m's long form.
|
|
6675
|
+
push: ["--message"],
|
|
6676
|
+
// db: refused by ez db sql itself, with the reason (one App Database for the app and every Preview).
|
|
6677
|
+
db: ["--preview"],
|
|
6678
|
+
});
|
|
6679
|
+
/**
|
|
6680
|
+
* The flags a command takes: those its usage lines name, plus EVERY_COMMAND_FLAGS and MORE_FLAGS.
|
|
6681
|
+
* @param {string} name
|
|
6682
|
+
*/
|
|
6683
|
+
const commandFlags = (name) =>
|
|
6684
|
+
new Set([
|
|
6685
|
+
...COMMANDS.filter(isUsageOf(name)).flatMap((c) => c.usage.match(/--[a-z][a-z0-9-]*/g) ?? []),
|
|
6686
|
+
...EVERY_COMMAND_FLAGS,
|
|
6687
|
+
...(MORE_FLAGS[name] ?? []),
|
|
6688
|
+
]);
|
|
6689
|
+
/** What a flag looks like; other words that start with `--` (an SQL comment) are arguments. */
|
|
6690
|
+
const FLAG_RE = /^--[a-z][a-z0-9-]*$/;
|
|
6691
|
+
|
|
6479
6692
|
/**
|
|
6480
6693
|
* Usage + help prose for every `ez` line. `HELP` and `COMMAND_NAMES` are derived from this.
|
|
6481
6694
|
* @type {typeof import("./commands.d.mts").COMMANDS}
|
|
@@ -6530,13 +6743,21 @@ export const COMMANDS = [
|
|
|
6530
6743
|
help: "run a command in the Global Working Copy: pull, cat db/types.d.ts, put db/schema.sql, check, push",
|
|
6531
6744
|
},
|
|
6532
6745
|
{
|
|
6533
|
-
usage: "ez help [<topic> | all]",
|
|
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);
|
|
6746
|
+
usage: "ez help [<topic> | <command> | all]",
|
|
6747
|
+
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); a command's name (or `ez <command> --help`) prints its usage; all, everything",
|
|
6535
6748
|
},
|
|
6536
6749
|
{
|
|
6537
6750
|
usage: "ez status",
|
|
6538
6751
|
help: "the shared files' version, what you pulled, your unpushed changes, what deploy would do to the schema and which Global changes it brings in",
|
|
6539
6752
|
},
|
|
6753
|
+
{
|
|
6754
|
+
usage: "ez diff [<path>]",
|
|
6755
|
+
help: "your Working Copy line by line against the shared files (every file that differs, or one): what a push would change; `ez global diff` for the Global Workspace",
|
|
6756
|
+
},
|
|
6757
|
+
{
|
|
6758
|
+
usage: "ez global starter [<path> | add <path>... [--force]]",
|
|
6759
|
+
help: "your Global Workspace against this CLI's starter (docs/adr/0215): the starter files you lack, the ones that differ, one file's diff; add copies starter files in (--force replaces yours), to check and push like any edit",
|
|
6760
|
+
},
|
|
6540
6761
|
{
|
|
6541
6762
|
usage: "ez pull [--force] [--version <n>] [--all]",
|
|
6542
6763
|
help: "replace the working copy with the shared files (--force overwrites tracked files; untracked files are kept; --version restores a retained Version; --all refreshes every Site from the Instance folder)",
|
|
@@ -6790,6 +7011,116 @@ export const COMMAND_NAMES = Object.freeze([
|
|
|
6790
7011
|
|
|
6791
7012
|
/** @param {string} line */
|
|
6792
7013
|
const usage = (line) => new Error(`Usage: ${line}`);
|
|
7014
|
+
|
|
7015
|
+
/** A text's lines, without the empty one after a final newline. @param {string} text */
|
|
7016
|
+
const linesOf = (text) => {
|
|
7017
|
+
const lines = text.split("\n");
|
|
7018
|
+
if (lines.at(-1) === "") lines.pop();
|
|
7019
|
+
return lines;
|
|
7020
|
+
};
|
|
7021
|
+
/** Past this many edits a diff says the files differ instead of listing them (Myers keeps one row per edit). */
|
|
7022
|
+
const DIFF_MAX_EDITS = 4000;
|
|
7023
|
+
/**
|
|
7024
|
+
* The edit script from lines `a` to lines `b` (Myers, O((N+M)D)): [" ", line] kept, ["-", line] removed,
|
|
7025
|
+
* ["+", line] added, in order; null past DIFF_MAX_EDITS edits.
|
|
7026
|
+
* @param {string[]} a @param {string[]} b @returns {[" " | "-" | "+", string][] | null}
|
|
7027
|
+
*/
|
|
7028
|
+
function lineEdits(a, b) {
|
|
7029
|
+
const n = a.length;
|
|
7030
|
+
const m = b.length;
|
|
7031
|
+
const max = n + m;
|
|
7032
|
+
const v = new Int32Array(2 * max + 2);
|
|
7033
|
+
/** @type {Int32Array[]} */
|
|
7034
|
+
const trace = [];
|
|
7035
|
+
/** @param {Int32Array} row @param {number} k */
|
|
7036
|
+
const at = (row, k) => row[k + max] ?? 0;
|
|
7037
|
+
/** @param {Int32Array} row @param {number} k @param {number} d */
|
|
7038
|
+
const down = (row, k, d) => k === -d || (k !== d && at(row, k - 1) < at(row, k + 1));
|
|
7039
|
+
search: for (let d = 0; d <= max; d++) {
|
|
7040
|
+
if (d > DIFF_MAX_EDITS) return null;
|
|
7041
|
+
trace.push(v.slice());
|
|
7042
|
+
for (let k = -d; k <= d; k += 2) {
|
|
7043
|
+
let x = down(v, k, d) ? at(v, k + 1) : at(v, k - 1) + 1;
|
|
7044
|
+
let y = x - k;
|
|
7045
|
+
while (x < n && y < m && a[x] === b[y]) {
|
|
7046
|
+
x++;
|
|
7047
|
+
y++;
|
|
7048
|
+
}
|
|
7049
|
+
v[k + max] = x;
|
|
7050
|
+
if (x >= n && y >= m) break search;
|
|
7051
|
+
}
|
|
7052
|
+
}
|
|
7053
|
+
/** @type {[" " | "-" | "+", string][]} */
|
|
7054
|
+
const edits = [];
|
|
7055
|
+
let x = n;
|
|
7056
|
+
let y = m;
|
|
7057
|
+
for (let d = trace.length - 1; d >= 0 && (x > 0 || y > 0); d--) {
|
|
7058
|
+
const row = trace[d] ?? v;
|
|
7059
|
+
const k = x - y;
|
|
7060
|
+
const prevK = down(row, k, d) ? k + 1 : k - 1;
|
|
7061
|
+
const prevX = at(row, prevK);
|
|
7062
|
+
const prevY = prevX - prevK;
|
|
7063
|
+
while (x > prevX && y > prevY) {
|
|
7064
|
+
x--;
|
|
7065
|
+
y--;
|
|
7066
|
+
edits.push([" ", a[x] ?? ""]);
|
|
7067
|
+
}
|
|
7068
|
+
if (d === 0) break;
|
|
7069
|
+
if (x === prevX) {
|
|
7070
|
+
y--;
|
|
7071
|
+
edits.push(["+", b[y] ?? ""]);
|
|
7072
|
+
} else {
|
|
7073
|
+
x--;
|
|
7074
|
+
edits.push(["-", a[x] ?? ""]);
|
|
7075
|
+
}
|
|
7076
|
+
}
|
|
7077
|
+
return edits.reverse();
|
|
7078
|
+
}
|
|
7079
|
+
/**
|
|
7080
|
+
* A unified diff (3 lines of context) from `before` to `after`, labelled `from` and `to`; null is a file that
|
|
7081
|
+
* does not exist on that side. Empty when they are equal.
|
|
7082
|
+
* @param {string | null} before @param {string | null} after @param {string} from @param {string} to
|
|
7083
|
+
*/
|
|
7084
|
+
function unifiedDiff(before, after, from, to) {
|
|
7085
|
+
if (before === after) return "";
|
|
7086
|
+
const head = [
|
|
7087
|
+
`--- ${before === null ? "/dev/null" : from}`,
|
|
7088
|
+
`+++ ${after === null ? "/dev/null" : to}`,
|
|
7089
|
+
];
|
|
7090
|
+
const edits = lineEdits(linesOf(before ?? ""), linesOf(after ?? ""));
|
|
7091
|
+
if (!edits) return [...head, "(too different to show line by line)"].join("\n");
|
|
7092
|
+
if (!edits.some(([op]) => op !== " "))
|
|
7093
|
+
return [...head, "(only the final newline differs)"].join("\n");
|
|
7094
|
+
const CONTEXT = 3;
|
|
7095
|
+
/** @type {{ op: string, line: string, i: number, j: number }[]} */
|
|
7096
|
+
const rows = [];
|
|
7097
|
+
let i = 0;
|
|
7098
|
+
let j = 0;
|
|
7099
|
+
for (const [op, line] of edits) {
|
|
7100
|
+
rows.push({ op, line, i, j });
|
|
7101
|
+
if (op !== "+") i++;
|
|
7102
|
+
if (op !== "-") j++;
|
|
7103
|
+
}
|
|
7104
|
+
const changed = (/** @type {number} */ r) => (rows[r]?.op ?? " ") !== " ";
|
|
7105
|
+
const out = [...head];
|
|
7106
|
+
let next = 0;
|
|
7107
|
+
while (next < rows.length) {
|
|
7108
|
+
let start = next;
|
|
7109
|
+
while (start < rows.length && !changed(start)) start++;
|
|
7110
|
+
if (start >= rows.length) break;
|
|
7111
|
+
let end = start;
|
|
7112
|
+
for (let r = start + 1; r < rows.length && r - end <= 2 * CONTEXT; r++) if (changed(r)) end = r;
|
|
7113
|
+
const stop = Math.min(rows.length, end + CONTEXT + 1);
|
|
7114
|
+
const slice = rows.slice(Math.max(next, start - CONTEXT), stop);
|
|
7115
|
+
const old = slice.filter((r) => r.op !== "+").length;
|
|
7116
|
+
const now = slice.filter((r) => r.op !== "-").length;
|
|
7117
|
+
const first = slice[0] ?? { i: 0, j: 0 };
|
|
7118
|
+
out.push(`@@ -${old ? first.i + 1 : first.i},${old} +${now ? first.j + 1 : first.j},${now} @@`);
|
|
7119
|
+
for (const r of slice) out.push(`${r.op}${r.line}`);
|
|
7120
|
+
next = stop;
|
|
7121
|
+
}
|
|
7122
|
+
return out.join("\n");
|
|
7123
|
+
}
|
|
6793
7124
|
/** "2026-10-11 02:00 UTC": a schedule's due time. @param {number} ms */
|
|
6794
7125
|
const utcMinute = (ms) => `${new Date(ms).toISOString().slice(0, 16).replace("T", " ")} UTC`;
|
|
6795
7126
|
/**
|
|
@@ -6846,6 +7177,9 @@ export function ago(at) {
|
|
|
6846
7177
|
export const pinnedGlobalPath = (path) =>
|
|
6847
7178
|
path !== SESSION_FILE &&
|
|
6848
7179
|
path !== SCHEDULES_FILE &&
|
|
7180
|
+
path !== ACCESS_FILE &&
|
|
7181
|
+
ruleTableName(path) === null &&
|
|
7182
|
+
workflowTableName(path) === null &&
|
|
6849
7183
|
jobName(path) === null &&
|
|
6850
7184
|
path !== CONTEXT_FILE &&
|
|
6851
7185
|
docName(path) === null &&
|
|
@@ -6853,10 +7187,11 @@ export const pinnedGlobalPath = (path) =>
|
|
|
6853
7187
|
|
|
6854
7188
|
/**
|
|
6855
7189
|
* A Global push's two kinds of change (docs/adr/0224): Live ones took effect for every deployed Site at once;
|
|
6856
|
-
* the rest reach each Site at its next Preview or Deploy.
|
|
6857
|
-
*
|
|
7190
|
+
* the rest reach each Site at its next Preview or Deploy. `changed`: the files whose content differs from the
|
|
7191
|
+
* Version pushed over (every written file when that could not be read).
|
|
7192
|
+
* @param {import("./types.d.mts").PushResult} result @param {string[] | null} changed
|
|
6858
7193
|
*/
|
|
6859
|
-
function liveLines(result) {
|
|
7194
|
+
function liveLines(result, changed) {
|
|
6860
7195
|
const lines = [];
|
|
6861
7196
|
const live = result.live ?? [];
|
|
6862
7197
|
if (live.length) lines.push("Takes effect now:");
|
|
@@ -6927,7 +7262,7 @@ function liveLines(result) {
|
|
|
6927
7262
|
}`,
|
|
6928
7263
|
);
|
|
6929
7264
|
}
|
|
6930
|
-
const pinned = result.written.filter(pinnedGlobalPath);
|
|
7265
|
+
const pinned = (changed ?? result.written).filter(pinnedGlobalPath).sort();
|
|
6931
7266
|
if (pinned.length)
|
|
6932
7267
|
lines.push(`Takes effect at each Site's next Preview or Deploy: ${pinned.join(", ")}`);
|
|
6933
7268
|
return lines;
|
|
@@ -7109,6 +7444,10 @@ export function describeCommand(argv) {
|
|
|
7109
7444
|
return "Read the instructions";
|
|
7110
7445
|
case "status":
|
|
7111
7446
|
return "Checked the site's status";
|
|
7447
|
+
case "diff":
|
|
7448
|
+
return "Compared the working copy with the shared files";
|
|
7449
|
+
case "starter":
|
|
7450
|
+
return a === "add" ? "Copied starter files in" : "Compared with the starter";
|
|
7112
7451
|
case "pull":
|
|
7113
7452
|
return "Pulled the site's files";
|
|
7114
7453
|
case "push":
|
|
@@ -7371,6 +7710,23 @@ async function execute(ws, argv, stdin) {
|
|
|
7371
7710
|
}
|
|
7372
7711
|
const flags = new Set(args.filter((a) => a.startsWith("--")));
|
|
7373
7712
|
const pos = args.filter((a) => !a.startsWith("--"));
|
|
7713
|
+
// --help, and a flag the command does not take, never run it: an ignored flag ran the command as if it were
|
|
7714
|
+
// absent (`ez push --help` pushed, `ez global push --dryrun` would push for real).
|
|
7715
|
+
if ((COMMAND_NAMES.includes(cmd) || COMMANDS.some(isUsageOf(cmd))) && cmd !== "help") {
|
|
7716
|
+
if (flags.has("--help") || args.includes("-h")) {
|
|
7717
|
+
const text = commandHelp(cmd) ?? HELP;
|
|
7718
|
+
return out(text, { usage: text });
|
|
7719
|
+
}
|
|
7720
|
+
const known = commandFlags(cmd);
|
|
7721
|
+
const unknown = [...flags].filter((f) => FLAG_RE.test(f) && !known.has(f));
|
|
7722
|
+
// ez db sql refuses its own stray flags, saying to quote the statement.
|
|
7723
|
+
if (unknown.length && !(cmd === "db" && pos[0] === "sql"))
|
|
7724
|
+
throw usage(
|
|
7725
|
+
`${COMMANDS.filter(isUsageOf(cmd))
|
|
7726
|
+
.map((c) => c.usage)
|
|
7727
|
+
.join("\n ")}\nez ${cmd} takes no ${unknown.join(", ")}, so nothing was run.`,
|
|
7728
|
+
);
|
|
7729
|
+
}
|
|
7374
7730
|
// The Global Workspace is pushed, pulled and edited like a Site, and nothing else: it has no app, no
|
|
7375
7731
|
// database of its own, no settings, no members. Global Check validates its schema, Rules and types.
|
|
7376
7732
|
const global = ws.target?.site === GLOBAL_ID;
|
|
@@ -7556,11 +7912,106 @@ async function execute(ws, argv, stdin) {
|
|
|
7556
7912
|
const text = helpText(pos[0]);
|
|
7557
7913
|
if (text === null)
|
|
7558
7914
|
throw new Error(
|
|
7559
|
-
`No help topic "${pos[0]}". Topics: ${HELP_TOPICS.map((t) => t.name).join(", ")}, all.`,
|
|
7915
|
+
`No help topic or command "${pos[0]}". Topics: ${HELP_TOPICS.map((t) => t.name).join(", ")}, all; commands: ez help commands.`,
|
|
7560
7916
|
);
|
|
7561
7917
|
return out(text, { instructions: text });
|
|
7562
7918
|
}
|
|
7563
7919
|
|
|
7920
|
+
case "diff": {
|
|
7921
|
+
if (pos.length > 1) throw usage("ez diff [<path>]");
|
|
7922
|
+
const [local, shared] = await Promise.all([ws.files(), ws.fetchAll()]);
|
|
7923
|
+
const at = shared.version.n;
|
|
7924
|
+
const prefix = global ? `${GLOBAL_ID}/` : "";
|
|
7925
|
+
const [one] = pos;
|
|
7926
|
+
if (one !== undefined && !(one in local) && !(one in shared.files))
|
|
7927
|
+
throw new Error(`${one} is in neither your Working Copy nor the shared files (v${at}).`);
|
|
7928
|
+
const paths = (
|
|
7929
|
+
one !== undefined
|
|
7930
|
+
? [one]
|
|
7931
|
+
: [...new Set([...Object.keys(local), ...Object.keys(shared.files)])]
|
|
7932
|
+
)
|
|
7933
|
+
.filter((p) => local[p] !== shared.files[p])
|
|
7934
|
+
.sort();
|
|
7935
|
+
const diffs = paths.map((p) =>
|
|
7936
|
+
unifiedDiff(
|
|
7937
|
+
shared.files[p] ?? null,
|
|
7938
|
+
local[p] ?? null,
|
|
7939
|
+
`shared v${at} ${prefix}${p}`,
|
|
7940
|
+
`working copy ${prefix}${p}`,
|
|
7941
|
+
),
|
|
7942
|
+
);
|
|
7943
|
+
if (!diffs.length)
|
|
7944
|
+
return out(
|
|
7945
|
+
`${one === undefined ? "Your Working Copy is" : `${prefix}${one} is`} the same as the shared files (v${at}).`,
|
|
7946
|
+
{ version: at, changed: [] },
|
|
7947
|
+
);
|
|
7948
|
+
return out(diffs.join("\n"), { version: at, changed: paths });
|
|
7949
|
+
}
|
|
7950
|
+
|
|
7951
|
+
// The starter (docs/adr/0215) is copied in once; a later one reaches an Instance only by hand, so this
|
|
7952
|
+
// says what differs and copies a file in on request. Only the Global Workspace has one.
|
|
7953
|
+
case "starter": {
|
|
7954
|
+
if (!global)
|
|
7955
|
+
throw new Error(
|
|
7956
|
+
"The starter is the Global Workspace's: run `ez global starter` in a Site's folder.",
|
|
7957
|
+
);
|
|
7958
|
+
const local = await ws.files();
|
|
7959
|
+
const starter = STARTER_GLOBAL_FILES;
|
|
7960
|
+
const isStarter = (/** @type {string} */ p) => Object.hasOwn(starter, p);
|
|
7961
|
+
if (pos[0] === "add") {
|
|
7962
|
+
const paths = pos.slice(1);
|
|
7963
|
+
if (!paths.length) throw usage("ez global starter add <path>... [--force]");
|
|
7964
|
+
for (const p of paths) {
|
|
7965
|
+
if (!isStarter(p))
|
|
7966
|
+
throw new Error(`${p} is not a starter file. \`ez global starter\` lists them.`);
|
|
7967
|
+
if (p in local && local[p] !== starter[p] && !flags.has("--force"))
|
|
7968
|
+
throw new Error(
|
|
7969
|
+
`${GLOBAL_ID}/${p} differs from the starter's: see \`ez global starter ${p}\`, and add --force to replace yours. Nothing was copied.`,
|
|
7970
|
+
);
|
|
7971
|
+
}
|
|
7972
|
+
for (const p of paths) await ws.write(p, starter[p] ?? "");
|
|
7973
|
+
return out(
|
|
7974
|
+
`Copied ${paths.map((p) => `${GLOBAL_ID}/${p}`).join(", ")} from the starter. Run \`ez global check\`, then \`ez global push\` to share ${paths.length === 1 ? "it" : "them"}.`,
|
|
7975
|
+
{ copied: paths },
|
|
7976
|
+
);
|
|
7977
|
+
}
|
|
7978
|
+
if (pos.length > 1) throw usage("ez global starter [<path> | add <path>... [--force]]");
|
|
7979
|
+
const [one] = pos;
|
|
7980
|
+
if (one !== undefined) {
|
|
7981
|
+
if (!isStarter(one))
|
|
7982
|
+
throw new Error(`${one} is not a starter file. \`ez global starter\` lists them.`);
|
|
7983
|
+
const diff = unifiedDiff(
|
|
7984
|
+
starter[one] ?? "",
|
|
7985
|
+
local[one] ?? null,
|
|
7986
|
+
`starter ${one}`,
|
|
7987
|
+
`${GLOBAL_ID}/${one}`,
|
|
7988
|
+
);
|
|
7989
|
+
return out(diff || `${GLOBAL_ID}/${one} is the starter's.`, {
|
|
7990
|
+
path: one,
|
|
7991
|
+
same: !diff,
|
|
7992
|
+
missing: !(one in local),
|
|
7993
|
+
});
|
|
7994
|
+
}
|
|
7995
|
+
const all = Object.keys(starter).sort();
|
|
7996
|
+
const missing = all.filter((p) => !(p in local));
|
|
7997
|
+
const differs = all.filter((p) => p in local && local[p] !== starter[p]);
|
|
7998
|
+
const same = all.length - missing.length - differs.length;
|
|
7999
|
+
const lines = [
|
|
8000
|
+
`The starter has ${plural(all.length, "file")}; ${same} of yours ${same === 1 ? "is" : "are"} the same.`,
|
|
8001
|
+
];
|
|
8002
|
+
if (missing.length)
|
|
8003
|
+
lines.push(
|
|
8004
|
+
`Not in your Global (copy one in with \`ez global starter add <path>\`):`,
|
|
8005
|
+
...missing.map((p) => ` ${p}`),
|
|
8006
|
+
);
|
|
8007
|
+
if (differs.length)
|
|
8008
|
+
lines.push(
|
|
8009
|
+
`Differ from the starter (see one with \`ez global starter <path>\`):`,
|
|
8010
|
+
...differs.map((p) => ` ${p}`),
|
|
8011
|
+
);
|
|
8012
|
+
return out(lines.join("\n"), { missing, differs, same });
|
|
8013
|
+
}
|
|
8014
|
+
|
|
7564
8015
|
case "status": {
|
|
7565
8016
|
const [remote, files, pulled] = await Promise.all([
|
|
7566
8017
|
ws.remoteStatus(),
|
|
@@ -7708,9 +8159,19 @@ async function execute(ws, argv, stdin) {
|
|
|
7708
8159
|
if (global && flags.has("--dry-run")) options.dryRun = true;
|
|
7709
8160
|
if (global && flags.has("--acknowledge-exposure")) options.acknowledgeExposure = true;
|
|
7710
8161
|
if (global && flags.has("--force")) options.force = true;
|
|
8162
|
+
// What this push changes, to say what waits for each Site: a push sends every file, so compare with the
|
|
8163
|
+
// published Version rather than list them all.
|
|
8164
|
+
const published = global ? await ws.fetchAll().catch(() => null) : null;
|
|
8165
|
+
const changed = published?.files
|
|
8166
|
+
? Object.keys(files).filter((p) => published.files[p] !== files[p])
|
|
8167
|
+
: null;
|
|
7711
8168
|
const result = await ws.pushAll(files, flags.has("--prune"), deleted, options);
|
|
7712
8169
|
if (result.dryRun) {
|
|
7713
|
-
const dry = [
|
|
8170
|
+
const dry = [
|
|
8171
|
+
"Dry run: nothing was pushed.",
|
|
8172
|
+
...liveLines(result, changed),
|
|
8173
|
+
...reportLines(result),
|
|
8174
|
+
];
|
|
7714
8175
|
return out(dry.join("\n"), result);
|
|
7715
8176
|
}
|
|
7716
8177
|
await ws.setPulled({ version: result.version, hashes: hashAll(files) });
|
|
@@ -7718,7 +8179,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7718
8179
|
`Pushed ${plural(result.written.length, "file")} (${versionLine(result.version)}). ${global ? "Schema names and types are now permanent; Sites receive additions on their next Preview or Deploy." : "Run `ez deploy` to publish."}`,
|
|
7719
8180
|
];
|
|
7720
8181
|
for (const p of result.deleted) lines.push(`deleted ${p}`);
|
|
7721
|
-
if (global) lines.push(...liveLines(result), ...reportLines(result));
|
|
8182
|
+
if (global) lines.push(...liveLines(result, changed), ...reportLines(result));
|
|
7722
8183
|
return out(lines.join("\n"), result);
|
|
7723
8184
|
}
|
|
7724
8185
|
|
|
@@ -9061,7 +9522,7 @@ async function execute(ws, argv, stdin) {
|
|
|
9061
9522
|
const lines = [];
|
|
9062
9523
|
for (const t of tables) {
|
|
9063
9524
|
lines.push(
|
|
9064
|
-
`${t.name} ${plural(t.rows, "row")}${t.history ? ` the History of ${t.history} (read-only)` : ""}`,
|
|
9525
|
+
`${t.name} ${plural(t.rows, "row")}${t.history ? ` the History of ${t.history} (read-only)` : ""}${t.ruled ? " Table rules (ez db sql skips them)" : ""}`,
|
|
9065
9526
|
);
|
|
9066
9527
|
for (const [c, d] of Object.entries(t.columns)) lines.push(` ${c} ${d}`);
|
|
9067
9528
|
for (const cols of t.indexes) lines.push(` index (${cols.join(", ")})`);
|
|
@@ -9083,7 +9544,14 @@ async function execute(ws, argv, stdin) {
|
|
|
9083
9544
|
const statement = (pos.slice(1).join(" ") || stdin || "").trim();
|
|
9084
9545
|
if (!statement) throw usage("ez db sql <statement> (or pipe the statement on stdin)");
|
|
9085
9546
|
const r = await ws.dbSql(statement);
|
|
9086
|
-
if ("changed" in r)
|
|
9547
|
+
if ("changed" in r) {
|
|
9548
|
+
// Builder SQL runs no Table rules or workflow (docs/adr/0226): what they derive or refuse did not happen.
|
|
9549
|
+
const skipped = r.rulesSkipped ?? [];
|
|
9550
|
+
const note = skipped.length
|
|
9551
|
+
? `\n${skipped.join(", ")} ${skipped.length === 1 ? "has" : "have"} Table rules or a workflow, which Builder SQL does not run: set what they derive yourself, and check what they would refuse.`
|
|
9552
|
+
: "";
|
|
9553
|
+
return out(`Changed ${plural(r.changed, "row")}.${note}`, r);
|
|
9554
|
+
}
|
|
9087
9555
|
const cols = r.rows.length ? Object.keys(r.rows[0]) : [];
|
|
9088
9556
|
const lines = [cols.join("\t")];
|
|
9089
9557
|
for (const row of r.rows) lines.push(cols.map((c) => cellText(row[c])).join("\t"));
|
package/connections.mjs
CHANGED
package/editor-types.json.gz
CHANGED
|
Binary file
|
package/ez.mjs
CHANGED
|
@@ -942,8 +942,29 @@ function needsSite(cmd, args) {
|
|
|
942
942
|
);
|
|
943
943
|
}
|
|
944
944
|
|
|
945
|
+
/** The connection and account commands, which ez.mjs runs itself (`ez help` opens with them). */
|
|
946
|
+
const CONNECTION_HELP =
|
|
947
|
+
"Trial signup: ez signup [--email <email>] [--name <display name>] creates a private trial on the demo Host after email verification.\nConnections: ez login <instance or URL>; ez logins; ez switch <instance>; --instance targets one command; --account selects a saved account.\nWorking Copies stay bound to their Instance.\nAccount: ez account; ez tokens; ez token revoke <id>; ez logout [--instance <id>|--all].";
|
|
948
|
+
const COMMAND_USAGE =
|
|
949
|
+
"Usage: ez login|logout|logins|switch|whoami|sites|use|clone|init|dev|instance|site or ez help|status|pull|push|deploy|versions|check|preview|ls|cat|put|edit|delete|mv|config|builders|builder|users|user|audit|db|support|email";
|
|
950
|
+
|
|
945
951
|
async function main() {
|
|
946
952
|
const [cmd, ...args] = process.argv.slice(2);
|
|
953
|
+
// --help (or -h) never runs a command, here or in the contract: a contract command prints its usage
|
|
954
|
+
// (`ez global push --help` push's), the commands this file runs (login, clone, dev, ...) the overview.
|
|
955
|
+
if (
|
|
956
|
+
cmd &&
|
|
957
|
+
cmd !== "help" &&
|
|
958
|
+
cmd !== "--help" &&
|
|
959
|
+
(args.includes("--help") || args.includes("-h"))
|
|
960
|
+
) {
|
|
961
|
+
// `ez global starter --help`: the Global subcommand's usage when it has one, else global's.
|
|
962
|
+
const topic = cmd === "global" && args[0] && !args[0].startsWith("-") ? args[0] : cmd;
|
|
963
|
+
const help = (/** @type {string} */ t) =>
|
|
964
|
+
runCommand(/** @type {Workspace} */ ({}), ["help", t]).catch(() => null);
|
|
965
|
+
if (COMMAND_NAMES.includes(cmd)) return console.log((await help(topic)) ?? (await help(cmd)));
|
|
966
|
+
return console.log(`${COMMAND_USAGE}\n${CONNECTION_HELP}`);
|
|
967
|
+
}
|
|
947
968
|
if (cmd === "signup") {
|
|
948
969
|
if (
|
|
949
970
|
args.some((arg, index) => index % 2 === 0 && !["--email", "--name"].includes(arg)) ||
|
|
@@ -996,10 +1017,7 @@ async function main() {
|
|
|
996
1017
|
}
|
|
997
1018
|
if (cmd === "help" || !cmd || cmd === "--help") {
|
|
998
1019
|
// The connection lines open the top-level help only; a topic (`ez help rules`) is just the topic.
|
|
999
|
-
if (!args.length)
|
|
1000
|
-
console.log(
|
|
1001
|
-
"Trial signup: ez signup [--email <email>] [--name <display name>] creates a private trial on the demo Host after email verification.\nConnections: ez login <instance or URL>; ez logins; ez switch <instance>; --instance targets one command; --account selects a saved account.\nWorking Copies stay bound to their Instance.\nAccount: ez account; ez tokens; ez token revoke <id>; ez logout [--instance <id>|--all].",
|
|
1002
|
-
);
|
|
1020
|
+
if (!args.length) console.log(CONNECTION_HELP);
|
|
1003
1021
|
// Help does not read any Workspace methods.
|
|
1004
1022
|
return console.log(await runCommand(/** @type {Workspace} */ ({}), ["help", ...args]));
|
|
1005
1023
|
}
|
|
@@ -1102,9 +1120,7 @@ async function main() {
|
|
|
1102
1120
|
}
|
|
1103
1121
|
|
|
1104
1122
|
if (!COMMAND_NAMES.includes(cmd)) {
|
|
1105
|
-
console.log(
|
|
1106
|
-
"Usage: ez login|logout|logins|switch|whoami|sites|use|clone|init|dev|instance|site or ez help|status|pull|push|deploy|versions|check|preview|ls|cat|put|edit|delete|mv|config|builders|builder|users|user|audit|db|support|email",
|
|
1107
|
-
);
|
|
1123
|
+
console.log(COMMAND_USAGE);
|
|
1108
1124
|
process.exitCode = 1;
|
|
1109
1125
|
return;
|
|
1110
1126
|
}
|
package/package.json
CHANGED
package/paths.d.mts
CHANGED
|
@@ -11,6 +11,8 @@ export const ACCESS_RULES_PATH: "/_ez/access";
|
|
|
11
11
|
/** The active scope's values for the Framework's switcher (docs/adr/0225). */
|
|
12
12
|
export const SCOPE_PATH: "/_ez/scope";
|
|
13
13
|
export const VERSIONS_HEADER: "ez-versions";
|
|
14
|
+
/** A Preview page's first screen is complete (docs/adr/0212): the app host's swap shows it then. */
|
|
15
|
+
export const FIRST_SCREEN_EVENT: "ez:first-screen";
|
|
14
16
|
/** Session State (docs/adr/0214): the page's path and the viewer's own counter in the live version map. */
|
|
15
17
|
export const SESSION_PATH: "/_ez/session";
|
|
16
18
|
export const SESSION_VERSION_KEY: "~session";
|
package/paths.mjs
CHANGED
|
@@ -37,6 +37,14 @@ export const SCOPE_PATH = "/_ez/scope";
|
|
|
37
37
|
*/
|
|
38
38
|
export const VERSIONS_HEADER = "ez-versions";
|
|
39
39
|
|
|
40
|
+
/**
|
|
41
|
+
* The window event a Preview page's Framework dispatches once, when its first screen is complete (docs/adr/0212):
|
|
42
|
+
* the Shell and the page have committed and no request of the Framework's has been in flight for a moment. The
|
|
43
|
+
* app host's swap holds the last build's screen over the page until it.
|
|
44
|
+
* @type {typeof import("./paths.d.mts").FIRST_SCREEN_EVENT}
|
|
45
|
+
*/
|
|
46
|
+
export const FIRST_SCREEN_EVENT = "ez:first-screen";
|
|
47
|
+
|
|
40
48
|
/** Where a page reads (GET) and writes (PUT `/<key>`) its viewer's Session State, under the Site's prefix. */
|
|
41
49
|
export const SESSION_PATH = "/_ez/session";
|
|
42
50
|
/** The viewer's own counter in the live version map (docs/adr/0220); no Table can have this name. */
|
package/schema.d.mts
CHANGED
|
@@ -295,12 +295,21 @@ export function checkSql(
|
|
|
295
295
|
instance: string,
|
|
296
296
|
):
|
|
297
297
|
| { kind: "read"; sql: string; tables: string[] }
|
|
298
|
-
| {
|
|
298
|
+
| {
|
|
299
|
+
kind: "write";
|
|
300
|
+
sql: string;
|
|
301
|
+
/** every Table the statement names */
|
|
302
|
+
tables: string[];
|
|
303
|
+
/** the Tables it writes (an INSERT's, UPDATE's or DELETE's target), not those it only reads */
|
|
304
|
+
written: string[];
|
|
305
|
+
verb: "INSERT" | "UPDATE" | "DELETE";
|
|
306
|
+
}
|
|
299
307
|
| { error: string };
|
|
300
308
|
export function helpDb(): string;
|
|
301
309
|
/** `ez help access`'s access.sql reference. */
|
|
302
310
|
export function helpAccess(): string;
|
|
303
|
-
|
|
311
|
+
/** `ez db schema`'s answer: the live schema and the Tables whose writes run Table rules or a workflow. */
|
|
312
|
+
export function renderSchema(schema: LiveSchema & { ruled?: string[] }): string;
|
|
304
313
|
|
|
305
314
|
export const TYPES_HEADER: string;
|
|
306
315
|
export function aliasName(table: string): string;
|
package/schema.mjs
CHANGED
|
@@ -2652,7 +2652,16 @@ export function checkSql(statement, tables, instance) {
|
|
|
2652
2652
|
const verb = (
|
|
2653
2653
|
first === "WITH" ? (/\b(INSERT|UPDATE|DELETE)\b/i.exec(blank)?.[1] ?? "") : first
|
|
2654
2654
|
).toUpperCase();
|
|
2655
|
-
|
|
2655
|
+
const written = [
|
|
2656
|
+
...new Set(replacements.filter(([, r]) => r.write).map(([, r]) => r.table)),
|
|
2657
|
+
].sort();
|
|
2658
|
+
return {
|
|
2659
|
+
kind,
|
|
2660
|
+
sql,
|
|
2661
|
+
tables: named,
|
|
2662
|
+
written,
|
|
2663
|
+
verb: /** @type {typeof SQL_WRITE[number]} */ (verb),
|
|
2664
|
+
};
|
|
2656
2665
|
}
|
|
2657
2666
|
|
|
2658
2667
|
// ---- ez help access (the access.sql part) -----------------------------------------------------------------
|
|
@@ -2781,8 +2790,10 @@ any write to a child it names, in that write, up to 10 steps and 3 Tables up. Pa
|
|
|
2781
2790
|
lists what the viewer could run now ({ name, label, to, enabled, reason }), useCan(table,
|
|
2782
2791
|
"transition:<action>", row) answers without a request, useWorkflow(table) gives labels and tones.
|
|
2783
2792
|
Names and types become permanent at the first global Push, before any Preview or Deploy. Published
|
|
2784
|
-
columns, references, enum values, sequences, indexes and policies cannot be removed or changed
|
|
2785
|
-
|
|
2793
|
+
columns, references, enum values, sequences, indexes and policies cannot be removed or changed (a CHECK
|
|
2794
|
+
list cannot gain a value either: add a column with the longer list); the one relaxation is that
|
|
2795
|
+
a unique index may become a plain index. Correct a typo by adding a column. \`ez global check\` names a
|
|
2796
|
+
refused change.
|
|
2786
2797
|
Backfilling rows does not synchronize old and new writers.
|
|
2787
2798
|
After editing, run \`ez global check\` and \`ez global push\`. Push records definitions without DDL;
|
|
2788
2799
|
a successful Site Preview or Deploy creates missing Tables, columns and indexes. Unpushed schema
|
|
@@ -2896,7 +2907,7 @@ Builders: ez db actors '{"where":{"kind":"builder"}}'.`;
|
|
|
2896
2907
|
|
|
2897
2908
|
/**
|
|
2898
2909
|
* The live schema as CREATE TABLE statements: each column as a registered Declaration has it, else its
|
|
2899
|
-
* storage type; a History says whose it is.
|
|
2910
|
+
* storage type; a History says whose it is, and a Table whose writes run Table rules or a workflow says so.
|
|
2900
2911
|
* @type {typeof import("./schema.d.mts").renderSchema}
|
|
2901
2912
|
*/
|
|
2902
2913
|
export function renderSchema(schema) {
|
|
@@ -2924,6 +2935,8 @@ export function renderSchema(schema) {
|
|
|
2924
2935
|
out.push(
|
|
2925
2936
|
`-- ${t}: the History of ${parent} (read-only; every change to ${parent}, see ez help db)`,
|
|
2926
2937
|
);
|
|
2938
|
+
if (schema.ruled?.includes(t))
|
|
2939
|
+
out.push(`-- ${t}: its writes run Table rules or a workflow, which ez db sql does not run`);
|
|
2927
2940
|
out.push(`CREATE TABLE ${t} (`);
|
|
2928
2941
|
out.push(
|
|
2929
2942
|
Object.entries(live.columns)
|
package/types.d.mts
CHANGED
|
@@ -520,11 +520,17 @@ export type TableInfo = {
|
|
|
520
520
|
sites: string[];
|
|
521
521
|
/** the Table this is the History of (docs/adr/0218), or null for a Table */
|
|
522
522
|
history: string | null;
|
|
523
|
+
/** its writes run Table rules or a workflow (docs/adr/0226, 0227), which `ez db sql` does not run */
|
|
524
|
+
ruled?: boolean;
|
|
523
525
|
};
|
|
524
526
|
/** `ez db sql`: rows for a read (capped, `truncated` says so), changed-row count for a write. */
|
|
525
527
|
export type SqlResult =
|
|
526
528
|
| { rows: Record<string, unknown>[]; truncated: boolean }
|
|
527
|
-
| {
|
|
529
|
+
| {
|
|
530
|
+
changed: number;
|
|
531
|
+
/** the written Tables whose Table rules or workflow Builder SQL did not run (docs/adr/0226) */
|
|
532
|
+
rulesSkipped?: string[];
|
|
533
|
+
};
|
|
528
534
|
/** `ez db redact` (docs/adr/0218): declared columns of a Table to blank in its rows and their History. */
|
|
529
535
|
export type RedactInput = {
|
|
530
536
|
table: string;
|
|
@@ -737,16 +743,36 @@ export type ScheduleRun = {
|
|
|
737
743
|
startedAt: number;
|
|
738
744
|
finishedAt: number | null;
|
|
739
745
|
};
|
|
740
|
-
/**
|
|
741
|
-
* What ezship Desktop's preload exposes as `window.ezDesktop` (ADR 0235); absent in a browser. `call` runs
|
|
742
|
-
* one local function of the Site under `prefix` from the artifact with that build id and answers its result.
|
|
743
|
-
*/
|
|
744
746
|
/** What the Desktop hands a local function (ADR 0235): the Member, the Site and this computer's folder for it. */
|
|
745
747
|
export type LocalContext = {
|
|
746
748
|
user: Readonly<{ id: string; email: string; name: string | null }>;
|
|
747
749
|
site: Readonly<{ instance: string; id: string; prefix: string }>;
|
|
748
750
|
desktop: Readonly<{ version: string; dataDir: string }>;
|
|
749
751
|
};
|
|
752
|
+
/**
|
|
753
|
+
* What a `local/<name>.ts` default-exports (ADR 0250): a call answered within 60 seconds, a stream a page
|
|
754
|
+
* reads while it is open, or a service the Desktop keeps running while it has the Instance open.
|
|
755
|
+
*/
|
|
756
|
+
export type LocalKind = "function" | "stream" | "service";
|
|
757
|
+
/**
|
|
758
|
+
* Private build output (ADRs 0235 and 0250): a Site's local functions as one CommonJS module whose
|
|
759
|
+
* `invoke(context, name, input, runtime)` runs one of them. `kinds` names each one's kind; an artifact built
|
|
760
|
+
* before ADR 0250 has none, and every name in it is a function.
|
|
761
|
+
*/
|
|
762
|
+
export type LocalArtifact = {
|
|
763
|
+
id: string;
|
|
764
|
+
names: string[];
|
|
765
|
+
kinds?: Record<string, LocalKind>;
|
|
766
|
+
code: string;
|
|
767
|
+
};
|
|
768
|
+
/**
|
|
769
|
+
* What the Desktop hands the local artifact's `invoke` beside the context (ADR 0250). `callServer` runs the
|
|
770
|
+
* Site's server function `name` of the server build `artifact` over the signed-in Member's session, exactly
|
|
771
|
+
* as a page's call does, and answers its result; the local code never sees the session.
|
|
772
|
+
*/
|
|
773
|
+
export type LocalRuntime = {
|
|
774
|
+
callServer(artifact: string, name: string, input: unknown): Promise<unknown>;
|
|
775
|
+
};
|
|
750
776
|
/** One published Desktop release file (ADR 0235), as the operator API lists it. */
|
|
751
777
|
export type DesktopFile = {
|
|
752
778
|
filename: string;
|
|
@@ -754,10 +780,27 @@ export type DesktopFile = {
|
|
|
754
780
|
size: number;
|
|
755
781
|
uploadedAt: number;
|
|
756
782
|
};
|
|
783
|
+
/**
|
|
784
|
+
* What ezship Desktop's preload exposes as `window.ezDesktop` (ADR 0235); absent in a browser. `call` runs
|
|
785
|
+
* one local function of the Site under `prefix` from the artifact with that build id and answers its result.
|
|
786
|
+
* `stream` opens a local stream (ADR 0250) and reads it value by value; `return()` ends it early, and the
|
|
787
|
+
* Desktop ends it when the page leaves.
|
|
788
|
+
*/
|
|
757
789
|
export type DesktopBridge = {
|
|
758
790
|
version: string;
|
|
759
791
|
call(prefix: string, artifact: string, name: string, input: unknown): Promise<unknown>;
|
|
792
|
+
stream?(prefix: string, artifact: string, name: string, input: unknown): LocalStreamReader;
|
|
760
793
|
};
|
|
794
|
+
/** A local stream as the page reads it across the Desktop's bridge: an async iterator, no more. */
|
|
795
|
+
export type LocalStreamReader = {
|
|
796
|
+
next(): Promise<{ done: boolean; value?: unknown }>;
|
|
797
|
+
return(): Promise<{ done: boolean; value?: unknown }>;
|
|
798
|
+
};
|
|
799
|
+
/**
|
|
800
|
+
* `GET /_ez/sites` on an Instance's app origin (ADR 0250): the Sites the signed-in Member may open, with when
|
|
801
|
+
* each was last deployed, so the Desktop starts their local services and restarts them after a deploy.
|
|
802
|
+
*/
|
|
803
|
+
export type MemberSites = { sites: { id: string; name: string; deployedAt: number | null }[] };
|
|
761
804
|
/** Private build output (docs/adr/0233): every Global Document of the build's snapshot, compiled for QuickJS. */
|
|
762
805
|
export type DocumentArtifact = { id: string; names: string[]; code: string };
|
|
763
806
|
/** One element of a rendered Document, as the template stage returns it and the renderer reads it. */
|