ezship 0.1.18 → 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 +17 -4
- package/commands.mjs +501 -37
- package/connections.mjs +2 -0
- package/editor-types.json.gz +0 -0
- package/ez.mjs +23 -7
- package/package.json +1 -1
- 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;
|
|
@@ -631,8 +644,8 @@ export function hashContent(s: string): string;
|
|
|
631
644
|
export function localChanges(files: Record<string, string>, pulled: Pulled | null): Changes;
|
|
632
645
|
/**
|
|
633
646
|
* Whether a change to this Global Workspace file reaches a deployed Site only at its next Preview or Deploy
|
|
634
|
-
* (docs/adr/0224): false for the Live-only files (session.ts, schedules.json,
|
|
635
|
-
* 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).
|
|
636
649
|
*/
|
|
637
650
|
export function pinnedGlobalPath(path: string): boolean;
|
|
638
651
|
/**
|
|
@@ -657,7 +670,7 @@ export const HELP: string;
|
|
|
657
670
|
export const INSTRUCTIONS: string;
|
|
658
671
|
/** `ez help <topic>`, in index order. */
|
|
659
672
|
export const HELP_TOPICS: readonly { name: string; summary: string; text: () => string }[];
|
|
660
|
-
/** `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. */
|
|
661
674
|
export function helpText(topic?: string): string | null;
|
|
662
675
|
/** A complete example of `ez help recipes`; the Pipeline's tests build each against the starter Global. */
|
|
663
676
|
export type Recipe = {
|
package/commands.mjs
CHANGED
|
@@ -168,11 +168,113 @@ export const LOCAL_DIR = "local/";
|
|
|
168
168
|
export const LOCAL_ARTIFACT = "_local/functions.json";
|
|
169
169
|
/** @type {typeof import("./commands.d.mts").LOCAL_BASE_PATH} */
|
|
170
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
|
+
}
|
|
171
262
|
/** @type {typeof import("./commands.d.mts").localFunctionName} */
|
|
172
263
|
export function localFunctionName(path) {
|
|
173
264
|
const match = /^local\/([a-z][A-Za-z0-9]{0,63})\.ts$/.exec(path);
|
|
174
265
|
return match ? match[1] : null;
|
|
175
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
|
+
}
|
|
176
278
|
/**
|
|
177
279
|
* jobs/<name>.ts in the Global Workspace: the Instance's scheduled jobs (ADR 0230), server code no browser
|
|
178
280
|
* can call; schedules.json runs them.
|
|
@@ -703,7 +805,7 @@ export function isValidFilePath(path) {
|
|
|
703
805
|
const INVALID_PATH = (p) =>
|
|
704
806
|
`Invalid path: ${p}. Use relative paths like components/Hello.tsx (no leading slash, no ..).`;
|
|
705
807
|
|
|
706
|
-
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.`;
|
|
707
809
|
|
|
708
810
|
/**
|
|
709
811
|
* Why required context is invalid, or null. Content quality is guided by the instructions, not parsed.
|
|
@@ -822,7 +924,7 @@ const hookPathError = (/** @type {string} */ path, /** @type {string} */ shape)
|
|
|
822
924
|
export function siteFileError(path) {
|
|
823
925
|
if (!isValidFilePath(path)) return INVALID_PATH(path);
|
|
824
926
|
if (functionName(path) || localFunctionName(path) || listenerName(path)) return null;
|
|
825
|
-
if (path === LISTENERS_FILE || path === PAGE_FILE) return null;
|
|
927
|
+
if (path === LISTENERS_FILE || path === PAGE_FILE || path === LOCAL_PACKAGES_FILE) return null;
|
|
826
928
|
if (path.startsWith(LISTENERS_DIR)) {
|
|
827
929
|
if (path.slice(LISTENERS_DIR.length).includes("/"))
|
|
828
930
|
return `${path}: listeners/ has no subfolders. ${SITE_SHAPE}`;
|
|
@@ -2755,6 +2857,7 @@ function resolveRelative(from, specifier) {
|
|
|
2755
2857
|
return parts.join("/");
|
|
2756
2858
|
}
|
|
2757
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.`;
|
|
2758
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).`;
|
|
2759
2862
|
/**
|
|
2760
2863
|
* A component of the Instance's Global Workspace, by its short name or by its path (`global/components/<Name>`,
|
|
@@ -2787,10 +2890,19 @@ export function importError(path, specifier, typeOnly, files) {
|
|
|
2787
2890
|
if (specifier.startsWith("node:")) return null;
|
|
2788
2891
|
if (NODE_BUILTINS.has(specifier.split("/")[0]))
|
|
2789
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.`;
|
|
2790
2900
|
const target = resolveRelative(path, specifier);
|
|
2791
2901
|
if (target === "constants") return null;
|
|
2792
2902
|
if (target && localFunctionName(target + ".ts") && target + ".ts" in files) return null;
|
|
2793
|
-
|
|
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}`;
|
|
2794
2906
|
}
|
|
2795
2907
|
// A Site's own lib module (ADR 0209): a Global lib module's imports, and the constants.
|
|
2796
2908
|
if (libModuleName(path)) {
|
|
@@ -3234,11 +3346,25 @@ export function checkStructure(files) {
|
|
|
3234
3346
|
for (const error of listeners.errors) top(LISTENERS_FILE, "listeners", error);
|
|
3235
3347
|
if (PAGE_FILE in files)
|
|
3236
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);
|
|
3237
3353
|
for (const warning of listeners.warnings) {
|
|
3238
3354
|
top(warning.split(" ")[0] ?? LISTENERS_FILE, "listener-unlisted", warning);
|
|
3239
3355
|
const last = out[out.length - 1];
|
|
3240
3356
|
if (last) last.severity = 2;
|
|
3241
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
|
+
);
|
|
3242
3368
|
for (const [path, source] of Object.entries(files)) {
|
|
3243
3369
|
const bad = siteFileError(path);
|
|
3244
3370
|
if (bad) {
|
|
@@ -3391,7 +3517,7 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3391
3517
|
[
|
|
3392
3518
|
"function-import",
|
|
3393
3519
|
"error",
|
|
3394
|
-
"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",
|
|
3395
3521
|
'import { serverFunction, z } from "@ezship/react/server"',
|
|
3396
3522
|
],
|
|
3397
3523
|
[
|
|
@@ -3423,6 +3549,24 @@ export const CHECK_RULES = Object.freeze(
|
|
|
3423
3549
|
["schedules", "error", "a schedules.json problem", "follow `ez help jobs`"],
|
|
3424
3550
|
["listeners", "error", "a listeners.json problem (docs/adr/0231)", "follow `ez help jobs`"],
|
|
3425
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
|
+
],
|
|
3426
3570
|
[
|
|
3427
3571
|
"listener-unlisted",
|
|
3428
3572
|
"warning",
|
|
@@ -3619,7 +3763,8 @@ export function helpRules() {
|
|
|
3619
3763
|
CHECK_RULES.filter((r) => r.severity === severity)
|
|
3620
3764
|
.map((r) => ` ${r.id.padEnd(width)} ${r.summary}\n ${" ".repeat(width)} fix: ${r.fix}`)
|
|
3621
3765
|
.join("\n");
|
|
3622
|
-
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,
|
|
3623
3768
|
a file and a line, and its message says what to write instead; \`ez check --json\` prints them as
|
|
3624
3769
|
[{ file, line, column, rule, severity, message }]. No rule sends an edit to apply: make the change the
|
|
3625
3770
|
message names. Errors fail the check; warnings never do.
|
|
@@ -4585,8 +4730,8 @@ db/schema.sql as last pushed) and the live data (the one production App Database
|
|
|
4585
4730
|
not types (run ez check first). Members see nothing until ez deploy. Live data: untouched.
|
|
4586
4731
|
ez global Global: your Global files become the Global Workspace's next Version, after ez global check
|
|
4587
4732
|
push passes for it and every Site (--force skips that; Admins only). SCHEMA IS PERMANENT HERE:
|
|
4588
|
-
published Tables, columns, types, CHECK
|
|
4589
|
-
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
|
|
4590
4735
|
new unique index, values a tightened type refuses). Takes effect NOW, for every deployed Site
|
|
4591
4736
|
and Preview: column defaults, db/access.sql, rules/, workflows/, SINGLETON, EXACTLY ONE OF,
|
|
4592
4737
|
ON DELETE RESTRICT, session.ts, jobs/ and schedules.json (the push lists them under "Takes
|
|
@@ -4917,7 +5062,8 @@ ${GLOBAL_FILES}
|
|
|
4917
5062
|
From react: useState, useActionState, useTransition, startTransition, useOptimistic, useMemo, useCallback
|
|
4918
5063
|
and types. A global component is global/<Name> or, by its path, global/components/<Name>. A page
|
|
4919
5064
|
imports \`import type { Provided } from "../App"\` for App.tsx's values (ez help frame).
|
|
4920
|
-
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
|
|
4921
5067
|
functions, ../lib/<name>, global/constants, global/lib/<name>, global/documents/<Name> and type-only
|
|
4922
5068
|
global/db/types.
|
|
4923
5069
|
Listeners: @ezship/react/server, constants, ../lib/<name>, global/constants, global/lib/<name>, type-only
|
|
@@ -4925,8 +5071,9 @@ ${GLOBAL_FILES}
|
|
|
4925
5071
|
Site lib (lib/): ${SITE_LIB_IMPORT_SHAPE}
|
|
4926
5072
|
Global jobs (global/jobs/): @ezship/react/server, global/lib/<name>, global/constants and type-only
|
|
4927
5073
|
global/db/types; nothing imports a job.
|
|
4928
|
-
Local functions (local/): @ezship/react/local, node:* built-ins,
|
|
4929
|
-
|
|
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.
|
|
4930
5077
|
constants.ts: nothing. Global code: ${GLOBAL_IMPORT_SHAPE}
|
|
4931
5078
|
Global lib: ${LIB_IMPORT_SHAPE}
|
|
4932
5079
|
Documents: ${DOCUMENT_IMPORT_SHAPE}
|
|
@@ -5574,20 +5721,44 @@ In local/readEmpty.ts:
|
|
|
5574
5721
|
});
|
|
5575
5722
|
UI imports ./local/readEmpty (../local/readEmpty from a page) and calls readEmpty({ path }) from an event
|
|
5576
5723
|
handler, or useCall(readEmpty, { path }) -> { result, loading, error, refresh } to run it when the page opens.
|
|
5577
|
-
A local function has every Node built-in (node:fs, node:path, node:os,
|
|
5578
|
-
the Member (user), the Site (site) and desktop.dataDir, a folder the
|
|
5579
|
-
|
|
5580
|
-
|
|
5581
|
-
|
|
5582
|
-
|
|
5583
|
-
|
|
5584
|
-
|
|
5585
|
-
|
|
5586
|
-
|
|
5587
|
-
|
|
5588
|
-
|
|
5589
|
-
|
|
5590
|
-
|
|
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).`;
|
|
5591
5762
|
|
|
5592
5763
|
/** `ez help documents` (ADR 0233). */
|
|
5593
5764
|
const DOCUMENTS_TOPIC = `Documents: PDFs from Global templates in \`global/documents/<Name>.tsx\` (\`ez global put documents/Invoice.tsx\`):
|
|
@@ -6465,7 +6636,8 @@ const helpIndex = () => {
|
|
|
6465
6636
|
};
|
|
6466
6637
|
|
|
6467
6638
|
/**
|
|
6468
|
-
* `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.
|
|
6469
6641
|
* @type {typeof import("./commands.d.mts").helpText}
|
|
6470
6642
|
*/
|
|
6471
6643
|
export function helpText(topic) {
|
|
@@ -6477,9 +6649,46 @@ export function helpText(topic) {
|
|
|
6477
6649
|
(t) => `==== ez help ${t.name}\n\n${t.text()}`,
|
|
6478
6650
|
),
|
|
6479
6651
|
].join("\n\n");
|
|
6480
|
-
return HELP_TOPICS.find((t) => t.name === topic)?.text() ??
|
|
6652
|
+
return HELP_TOPICS.find((t) => t.name === topic)?.text() ?? commandHelp(topic);
|
|
6481
6653
|
}
|
|
6482
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
|
+
|
|
6483
6692
|
/**
|
|
6484
6693
|
* Usage + help prose for every `ez` line. `HELP` and `COMMAND_NAMES` are derived from this.
|
|
6485
6694
|
* @type {typeof import("./commands.d.mts").COMMANDS}
|
|
@@ -6534,13 +6743,21 @@ export const COMMANDS = [
|
|
|
6534
6743
|
help: "run a command in the Global Working Copy: pull, cat db/types.d.ts, put db/schema.sql, check, push",
|
|
6535
6744
|
},
|
|
6536
6745
|
{
|
|
6537
|
-
usage: "ez help [<topic> | all]",
|
|
6538
|
-
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",
|
|
6539
6748
|
},
|
|
6540
6749
|
{
|
|
6541
6750
|
usage: "ez status",
|
|
6542
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",
|
|
6543
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
|
+
},
|
|
6544
6761
|
{
|
|
6545
6762
|
usage: "ez pull [--force] [--version <n>] [--all]",
|
|
6546
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)",
|
|
@@ -6794,6 +7011,116 @@ export const COMMAND_NAMES = Object.freeze([
|
|
|
6794
7011
|
|
|
6795
7012
|
/** @param {string} line */
|
|
6796
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
|
+
}
|
|
6797
7124
|
/** "2026-10-11 02:00 UTC": a schedule's due time. @param {number} ms */
|
|
6798
7125
|
const utcMinute = (ms) => `${new Date(ms).toISOString().slice(0, 16).replace("T", " ")} UTC`;
|
|
6799
7126
|
/**
|
|
@@ -6850,6 +7177,9 @@ export function ago(at) {
|
|
|
6850
7177
|
export const pinnedGlobalPath = (path) =>
|
|
6851
7178
|
path !== SESSION_FILE &&
|
|
6852
7179
|
path !== SCHEDULES_FILE &&
|
|
7180
|
+
path !== ACCESS_FILE &&
|
|
7181
|
+
ruleTableName(path) === null &&
|
|
7182
|
+
workflowTableName(path) === null &&
|
|
6853
7183
|
jobName(path) === null &&
|
|
6854
7184
|
path !== CONTEXT_FILE &&
|
|
6855
7185
|
docName(path) === null &&
|
|
@@ -6857,10 +7187,11 @@ export const pinnedGlobalPath = (path) =>
|
|
|
6857
7187
|
|
|
6858
7188
|
/**
|
|
6859
7189
|
* A Global push's two kinds of change (docs/adr/0224): Live ones took effect for every deployed Site at once;
|
|
6860
|
-
* the rest reach each Site at its next Preview or Deploy.
|
|
6861
|
-
*
|
|
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
|
|
6862
7193
|
*/
|
|
6863
|
-
function liveLines(result) {
|
|
7194
|
+
function liveLines(result, changed) {
|
|
6864
7195
|
const lines = [];
|
|
6865
7196
|
const live = result.live ?? [];
|
|
6866
7197
|
if (live.length) lines.push("Takes effect now:");
|
|
@@ -6931,7 +7262,7 @@ function liveLines(result) {
|
|
|
6931
7262
|
}`,
|
|
6932
7263
|
);
|
|
6933
7264
|
}
|
|
6934
|
-
const pinned = result.written.filter(pinnedGlobalPath);
|
|
7265
|
+
const pinned = (changed ?? result.written).filter(pinnedGlobalPath).sort();
|
|
6935
7266
|
if (pinned.length)
|
|
6936
7267
|
lines.push(`Takes effect at each Site's next Preview or Deploy: ${pinned.join(", ")}`);
|
|
6937
7268
|
return lines;
|
|
@@ -7113,6 +7444,10 @@ export function describeCommand(argv) {
|
|
|
7113
7444
|
return "Read the instructions";
|
|
7114
7445
|
case "status":
|
|
7115
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";
|
|
7116
7451
|
case "pull":
|
|
7117
7452
|
return "Pulled the site's files";
|
|
7118
7453
|
case "push":
|
|
@@ -7375,6 +7710,23 @@ async function execute(ws, argv, stdin) {
|
|
|
7375
7710
|
}
|
|
7376
7711
|
const flags = new Set(args.filter((a) => a.startsWith("--")));
|
|
7377
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
|
+
}
|
|
7378
7730
|
// The Global Workspace is pushed, pulled and edited like a Site, and nothing else: it has no app, no
|
|
7379
7731
|
// database of its own, no settings, no members. Global Check validates its schema, Rules and types.
|
|
7380
7732
|
const global = ws.target?.site === GLOBAL_ID;
|
|
@@ -7560,11 +7912,106 @@ async function execute(ws, argv, stdin) {
|
|
|
7560
7912
|
const text = helpText(pos[0]);
|
|
7561
7913
|
if (text === null)
|
|
7562
7914
|
throw new Error(
|
|
7563
|
-
`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.`,
|
|
7564
7916
|
);
|
|
7565
7917
|
return out(text, { instructions: text });
|
|
7566
7918
|
}
|
|
7567
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
|
+
|
|
7568
8015
|
case "status": {
|
|
7569
8016
|
const [remote, files, pulled] = await Promise.all([
|
|
7570
8017
|
ws.remoteStatus(),
|
|
@@ -7712,9 +8159,19 @@ async function execute(ws, argv, stdin) {
|
|
|
7712
8159
|
if (global && flags.has("--dry-run")) options.dryRun = true;
|
|
7713
8160
|
if (global && flags.has("--acknowledge-exposure")) options.acknowledgeExposure = true;
|
|
7714
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;
|
|
7715
8168
|
const result = await ws.pushAll(files, flags.has("--prune"), deleted, options);
|
|
7716
8169
|
if (result.dryRun) {
|
|
7717
|
-
const dry = [
|
|
8170
|
+
const dry = [
|
|
8171
|
+
"Dry run: nothing was pushed.",
|
|
8172
|
+
...liveLines(result, changed),
|
|
8173
|
+
...reportLines(result),
|
|
8174
|
+
];
|
|
7718
8175
|
return out(dry.join("\n"), result);
|
|
7719
8176
|
}
|
|
7720
8177
|
await ws.setPulled({ version: result.version, hashes: hashAll(files) });
|
|
@@ -7722,7 +8179,7 @@ async function execute(ws, argv, stdin) {
|
|
|
7722
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."}`,
|
|
7723
8180
|
];
|
|
7724
8181
|
for (const p of result.deleted) lines.push(`deleted ${p}`);
|
|
7725
|
-
if (global) lines.push(...liveLines(result), ...reportLines(result));
|
|
8182
|
+
if (global) lines.push(...liveLines(result, changed), ...reportLines(result));
|
|
7726
8183
|
return out(lines.join("\n"), result);
|
|
7727
8184
|
}
|
|
7728
8185
|
|
|
@@ -9065,7 +9522,7 @@ async function execute(ws, argv, stdin) {
|
|
|
9065
9522
|
const lines = [];
|
|
9066
9523
|
for (const t of tables) {
|
|
9067
9524
|
lines.push(
|
|
9068
|
-
`${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)" : ""}`,
|
|
9069
9526
|
);
|
|
9070
9527
|
for (const [c, d] of Object.entries(t.columns)) lines.push(` ${c} ${d}`);
|
|
9071
9528
|
for (const cols of t.indexes) lines.push(` index (${cols.join(", ")})`);
|
|
@@ -9087,7 +9544,14 @@ async function execute(ws, argv, stdin) {
|
|
|
9087
9544
|
const statement = (pos.slice(1).join(" ") || stdin || "").trim();
|
|
9088
9545
|
if (!statement) throw usage("ez db sql <statement> (or pipe the statement on stdin)");
|
|
9089
9546
|
const r = await ws.dbSql(statement);
|
|
9090
|
-
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
|
+
}
|
|
9091
9555
|
const cols = r.rows.length ? Object.keys(r.rows[0]) : [];
|
|
9092
9556
|
const lines = [cols.join("\t")];
|
|
9093
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/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. */
|