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 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, jobs/) and the files no app is
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 for an unknown topic. */
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
- return `${specifier}: local functions import @ezship/react/local, node:* built-ins, constants, sibling local functions, and type-only global/db/types.`;
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). Each problem names its rule id,
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 values, references and indexes can never be renamed
4589
- or removed. Push runs no DDL; it refuses a definition existing rows break (duplicates under a
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 types), constants, sibling
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, constants, sibling local functions and
4929
- type-only global/db/types; UI imports ./local/<name>; server and local functions never import each other.
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, node:child_process, node:net, ...),
5578
- the Member (user), the Site (site) and desktop.dataDir, a folder the Desktop keeps for this Site on this
5579
- computer; it has no db: the page saves results with db.insert or a server function.
5580
- [check] Local functions import only @ezship/react/local (localFunction, z and types), node:* built-ins (with
5581
- the prefix), constants, sibling local functions and type-only global/db/types; no packages.
5582
- [runtime] One call runs at most 60 seconds; input, result and errors cross as JSON. It is arbitrary Node code,
5583
- child processes included, on every Member's computer that opens the Site in ezship Desktop, and Members who
5584
- share a computer share its files. In an ordinary browser, the Studio's preview included, a call
5585
- fails and the Framework shows a notice that the app needs ezship Desktop; useDesktop() -> { available,
5586
- version } lets a page offer manual entry instead.
5587
- [advice] Use local functions for station configuration, caches, exports and exchanging files with programs on
5588
- that computer; the App Database stays the shared record, and nothing in a local file is visible to other
5589
- Members or computers. Never write credentials or Host tokens to disk. Test by opening the Preview URL in
5590
- ezship Desktop (ez preview prints it; ez dev keeps it fresh).`;
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 for an unknown topic.
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() ?? null;
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); all prints everything",
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
- * @param {import("./types.d.mts").PushResult} result
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 = ["Dry run: nothing was pushed.", ...liveLines(result), ...reportLines(result)];
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) return out(`Changed ${plural(r.changed, "row")}.`, 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
@@ -247,6 +247,8 @@ export function usesWorkingCopy(words) {
247
247
  return (
248
248
  [
249
249
  "status",
250
+ "diff",
251
+ "starter",
250
252
  "pull",
251
253
  "push",
252
254
  "check",
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ezship",
3
- "version": "0.1.18",
3
+ "version": "0.1.19",
4
4
  "description": "ez, the ezship command line. The same files as @ezship/cli.",
5
5
  "license": "Apache-2.0",
6
6
  "bin": {
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
- | { kind: "write"; sql: string; tables: string[]; verb: "INSERT" | "UPDATE" | "DELETE" }
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
- export function renderSchema(schema: LiveSchema): string;
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
- return { kind, sql, tables: named, verb: /** @type {typeof SQL_WRITE[number]} */ (verb) };
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; the one
2785
- relaxation is that a unique index may become a plain index. Correct a typo by adding a column.
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
- | { changed: number };
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. */