ezship 0.1.17 → 0.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/commands.d.mts CHANGED
@@ -9,6 +9,7 @@ import type {
9
9
  ListenerEntry,
10
10
  Listener,
11
11
  ListenerEvent,
12
+ LocalKind,
12
13
  ApiKey,
13
14
  ApiKeyInput,
14
15
  CreatedApiKey,
@@ -227,7 +228,7 @@ export interface Workspace {
227
228
  deletePreview(name: string): Promise<void>;
228
229
  /** A one-time link to the deployed app, or to the caller's Preview `preview` (docs/adr/0203). */
229
230
  appLink(preview?: string | null): Promise<AppLink>;
230
- dbSchema(): Promise<LiveSchema>;
231
+ dbSchema(): Promise<LiveSchema & { ruled?: string[] }>;
231
232
  dbTables(): Promise<TableInfo[]>;
232
233
  dbSql(statement: string): Promise<SqlResult>;
233
234
  dbAggregate(table: string, query: AggregateQuery): Promise<DataResult<AggregateRow>>;
@@ -334,7 +335,19 @@ export function functionName(path: string): string | null;
334
335
  export const LOCAL_DIR: "local/";
335
336
  export const LOCAL_ARTIFACT: "_local/functions.json";
336
337
  export const LOCAL_BASE_PATH: "/_ez/local";
338
+ export const MEMBER_SITES_PATH: "/_ez/sites";
339
+ export const LOCAL_SERVICE_MAX: 5;
340
+ export const DESKTOP_NATIVE_PACKAGES: readonly string[];
341
+ /** ADR 0250: the npm packages a Site's local functions import, name to exact version. */
342
+ export const LOCAL_PACKAGES_FILE: "local/packages.json";
343
+ export const LOCAL_PACKAGES_MAX: 30;
344
+ /** The packages of a local/packages.json that are right, and every problem with it. */
345
+ export function parseLocalPackages(source: string): {
346
+ packages: Record<string, string>;
347
+ errors: string[];
348
+ };
337
349
  export function localFunctionName(path: string): string | null;
350
+ export function localKindOf(source: string): LocalKind;
338
351
  /** Scheduled jobs (ADR 0230): the Global Workspace's jobs/<name>.ts, run by its schedules.json, never by a browser. */
339
352
  export const JOBS_DIR: "jobs/";
340
353
  export function jobName(path: string): string | null;
@@ -442,6 +455,7 @@ export {
442
455
  ATTACHMENT_TYPES,
443
456
  attachmentContentType,
444
457
  DOCUMENT_BASE_PATH,
458
+ FIRST_SCREEN_EVENT,
445
459
  FUNCTION_BASE_PATH,
446
460
  LIVE_STREAM_PATH,
447
461
  LIVE_VERSIONS_PATH,
@@ -630,8 +644,8 @@ export function hashContent(s: string): string;
630
644
  export function localChanges(files: Record<string, string>, pulled: Pulled | null): Changes;
631
645
  /**
632
646
  * Whether a change to this Global Workspace file reaches a deployed Site only at its next Preview or Deploy
633
- * (docs/adr/0224): false for the Live-only files (session.ts, schedules.json, jobs/) and the files no app is
634
- * built from (CONTEXT.md, docs/, the generated db/types.d.ts).
647
+ * (docs/adr/0224): false for the Live-only files (db/access.sql, rules/, workflows/, session.ts, schedules.json,
648
+ * jobs/) and the files no app is built from (CONTEXT.md, docs/, the generated db/types.d.ts).
635
649
  */
636
650
  export function pinnedGlobalPath(path: string): boolean;
637
651
  /**
@@ -656,7 +670,7 @@ export const HELP: string;
656
670
  export const INSTRUCTIONS: string;
657
671
  /** `ez help <topic>`, in index order. */
658
672
  export const HELP_TOPICS: readonly { name: string; summary: string; text: () => string }[];
659
- /** `ez help [<topic> | all]`'s text; null for an unknown topic. */
673
+ /** `ez help [<topic> | <command> | all]`'s text (a command's usage lines); null when neither names one. */
660
674
  export function helpText(topic?: string): string | null;
661
675
  /** A complete example of `ez help recipes`; the Pipeline's tests build each against the starter Global. */
662
676
  export type Recipe = {
package/commands.mjs CHANGED
@@ -37,6 +37,7 @@ export {
37
37
  ATTACHMENT_TYPES,
38
38
  attachmentContentType,
39
39
  DOCUMENT_BASE_PATH,
40
+ FIRST_SCREEN_EVENT,
40
41
  FUNCTION_BASE_PATH,
41
42
  LIVE_STREAM_PATH,
42
43
  LIVE_VERSIONS_PATH,
@@ -167,11 +168,113 @@ export const LOCAL_DIR = "local/";
167
168
  export const LOCAL_ARTIFACT = "_local/functions.json";
168
169
  /** @type {typeof import("./commands.d.mts").LOCAL_BASE_PATH} */
169
170
  export const LOCAL_BASE_PATH = "/_ez/local";
171
+ /**
172
+ * On an Instance's app origin, the Sites the signed-in Member may open with when each was deployed (ADR 0250):
173
+ * how the Desktop finds the local services to start.
174
+ * @type {typeof import("./commands.d.mts").MEMBER_SITES_PATH}
175
+ */
176
+ export const MEMBER_SITES_PATH = "/_ez/sites";
177
+ /**
178
+ * The most `localService` files a Site may hold (ADR 0250).
179
+ * @type {typeof import("./commands.d.mts").LOCAL_SERVICE_MAX}
180
+ */
181
+ export const LOCAL_SERVICE_MAX = 5;
182
+ /**
183
+ * Native packages ezship Desktop ships, built for it, which local functions import by name without listing
184
+ * them (ADR 0250). The list grows by Desktop release.
185
+ * @type {typeof import("./commands.d.mts").DESKTOP_NATIVE_PACKAGES}
186
+ */
187
+ export const DESKTOP_NATIVE_PACKAGES = Object.freeze(["serialport"]);
188
+ /**
189
+ * The optional Site file of npm packages its local functions import (ADR 0250): a JSON object of package name
190
+ * to exact version, which the Pipeline installs and bundles into the local artifact.
191
+ * @type {typeof import("./commands.d.mts").LOCAL_PACKAGES_FILE}
192
+ */
193
+ export const LOCAL_PACKAGES_FILE = "local/packages.json";
194
+ /** @type {typeof import("./commands.d.mts").LOCAL_PACKAGES_MAX} */
195
+ export const LOCAL_PACKAGES_MAX = 30;
196
+ /** An npm package name as the registry takes a new one: lowercase, optionally scoped, at most 214 characters. */
197
+ const NPM_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
198
+ /** One semantic version, nothing that resolves to several: no range, tag, URL, git or file spec. */
199
+ const EXACT_VERSION_RE =
200
+ /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
201
+ /**
202
+ * The package a bare specifier imports ("mqtt/lib/x" is mqtt, "@scope/name/x" is @scope/name), or null for a
203
+ * relative, `global/`, `node:` or malformed one.
204
+ * @param {string} specifier
205
+ */
206
+ function packageOf(specifier) {
207
+ if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("global/"))
208
+ return null;
209
+ if (specifier.startsWith("node:")) return null;
210
+ const parts = specifier.split("/");
211
+ const name = specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? "");
212
+ return NPM_NAME_RE.test(name) ? name : null;
213
+ }
214
+ /**
215
+ * The packages a local/packages.json lists and every problem with it (ADR 0250); `packages` holds the entries
216
+ * that are right, so an import of one of them is not refused for another entry's mistake.
217
+ * @type {typeof import("./commands.d.mts").parseLocalPackages}
218
+ */
219
+ export function parseLocalPackages(source) {
220
+ const shape = `${LOCAL_PACKAGES_FILE} is a JSON object of npm package names and exact versions: { "mqtt": "5.10.1" }.`;
221
+ let parsed;
222
+ try {
223
+ parsed = JSON.parse(source);
224
+ } catch (error) {
225
+ const why = error instanceof Error ? error.message : String(error);
226
+ return { packages: {}, errors: [`${LOCAL_PACKAGES_FILE} is not JSON: ${why}`] };
227
+ }
228
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
229
+ return { packages: {}, errors: [shape] };
230
+ const entries = Object.entries(parsed);
231
+ if (entries.length > LOCAL_PACKAGES_MAX)
232
+ return {
233
+ packages: {},
234
+ errors: [
235
+ `${LOCAL_PACKAGES_FILE} lists ${entries.length} packages; a Site lists at most ${LOCAL_PACKAGES_MAX}.`,
236
+ ],
237
+ };
238
+ /** @type {Record<string, string>} */
239
+ const packages = {};
240
+ /** @type {string[]} */
241
+ const errors = [];
242
+ for (const [name, version] of entries) {
243
+ const label = `${LOCAL_PACKAGES_FILE}: "${name}"`;
244
+ if (name.length > 214 || !NPM_NAME_RE.test(name))
245
+ errors.push(
246
+ `${label} is not an npm package name (lowercase, as npm shows it: "mqtt", "@scope/name").`,
247
+ );
248
+ else if (name.startsWith("@ezship/"))
249
+ errors.push(`${label}: the Framework comes with every Site; import @ezship/react/local.`);
250
+ else if (DESKTOP_NATIVE_PACKAGES.includes(name))
251
+ errors.push(`${label}: ezship Desktop ships it; import it without listing it.`);
252
+ else if (NODE_BUILTINS.has(name))
253
+ errors.push(`${label} is a Node built-in's name; import node:${name} without listing it.`);
254
+ else if (typeof version !== "string" || !EXACT_VERSION_RE.test(version))
255
+ errors.push(
256
+ `${label}: ${JSON.stringify(version)} is not an exact version; write the one version to install ("5.10.1"), never a range, tag, URL or path.`,
257
+ );
258
+ else packages[name] = version;
259
+ }
260
+ return { packages, errors };
261
+ }
170
262
  /** @type {typeof import("./commands.d.mts").localFunctionName} */
171
263
  export function localFunctionName(path) {
172
264
  const match = /^local\/([a-z][A-Za-z0-9]{0,63})\.ts$/.exec(path);
173
265
  return match ? match[1] : null;
174
266
  }
267
+ const LOCAL_FACTORY_RE =
268
+ /\bexport\s+default\s+(localFunction|localStream|localService)\s*(?:<[^()]*>)?\s*\(/;
269
+ /**
270
+ * The kind of local file `source` is (ADR 0250), by the factory it default-exports; the Rules make that
271
+ * export one call of one of the three factories, so anything else reads as a function.
272
+ * @type {typeof import("./commands.d.mts").localKindOf}
273
+ */
274
+ export function localKindOf(source) {
275
+ const factory = LOCAL_FACTORY_RE.exec(source)?.[1];
276
+ return factory === "localStream" ? "stream" : factory === "localService" ? "service" : "function";
277
+ }
175
278
  /**
176
279
  * jobs/<name>.ts in the Global Workspace: the Instance's scheduled jobs (ADR 0230), server code no browser
177
280
  * can call; schedules.json runs them.
@@ -702,7 +805,7 @@ export function isValidFilePath(path) {
702
805
  const INVALID_PATH = (p) =>
703
806
  `Invalid path: ${p}. Use relative paths like components/Hello.tsx (no leading slash, no ..).`;
704
807
 
705
- const SITE_SHAPE = `A Site is ${MAIN_FILE}, required ${CONTEXT_FILE}, ${PAGES_DIR}<route>.tsx, ${COMPONENTS_DIR}<Name>.tsx, ${HOOKS_DIR}use<Name>.ts, ${LIB_DIR}<name>.ts (helpers), ${FUNCTIONS_DIR}<name>.ts, ${LOCAL_DIR}<name>.ts, ${LISTENERS_DIR}<name>.ts, ${CONSTANTS_FILE}, ${DOCS_DIR}<name>.md (Markdown docs), optional ${LISTENERS_FILE}, optional ${PAGE_FILE} (the browser icon) and optional ${STYLE_FILE}. Schema, generated types and scheduled jobs belong to the Global Workspace.`;
808
+ const SITE_SHAPE = `A Site is ${MAIN_FILE}, required ${CONTEXT_FILE}, ${PAGES_DIR}<route>.tsx, ${COMPONENTS_DIR}<Name>.tsx, ${HOOKS_DIR}use<Name>.ts, ${LIB_DIR}<name>.ts (helpers), ${FUNCTIONS_DIR}<name>.ts, ${LOCAL_DIR}<name>.ts, ${LISTENERS_DIR}<name>.ts, ${CONSTANTS_FILE}, ${DOCS_DIR}<name>.md (Markdown docs), optional ${LISTENERS_FILE}, optional ${LOCAL_PACKAGES_FILE} (npm packages for local functions), optional ${PAGE_FILE} (the browser icon) and optional ${STYLE_FILE}. Schema, generated types and scheduled jobs belong to the Global Workspace.`;
706
809
 
707
810
  /**
708
811
  * Why required context is invalid, or null. Content quality is guided by the instructions, not parsed.
@@ -821,7 +924,7 @@ const hookPathError = (/** @type {string} */ path, /** @type {string} */ shape)
821
924
  export function siteFileError(path) {
822
925
  if (!isValidFilePath(path)) return INVALID_PATH(path);
823
926
  if (functionName(path) || localFunctionName(path) || listenerName(path)) return null;
824
- if (path === LISTENERS_FILE || path === PAGE_FILE) return null;
927
+ if (path === LISTENERS_FILE || path === PAGE_FILE || path === LOCAL_PACKAGES_FILE) return null;
825
928
  if (path.startsWith(LISTENERS_DIR)) {
826
929
  if (path.slice(LISTENERS_DIR.length).includes("/"))
827
930
  return `${path}: listeners/ has no subfolders. ${SITE_SHAPE}`;
@@ -1329,9 +1432,9 @@ a.card:hover { background: var(--hover); border-color: var(--line-strong); }
1329
1432
  .tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--line); overflow-x: auto; scrollbar-width: none; }
1330
1433
  .tabs .tab { position: relative; display: inline-flex; align-items: center; gap: 6px; min-height: 38px; padding: 0 12px; margin-bottom: -1px; border: 0; border-bottom: 2px solid transparent; background: none; color: var(--muted); font-weight: 500; text-decoration: none; white-space: nowrap; cursor: pointer; }
1331
1434
  .tabs .tab:hover { color: var(--text); }
1332
- .tabs .tab[aria-current] { color: var(--text); border-bottom-color: var(--primary); }
1435
+ .tabs .tab:is(button[aria-current], [aria-current="page"]) { color: var(--text); border-bottom-color: var(--primary); }
1333
1436
  .tabs .count { min-width: 20px; padding: 0 6px; border-radius: 999px; background: var(--surface-2); color: var(--muted); font-size: 0.75rem; line-height: 18px; text-align: center; font-variant-numeric: tabular-nums; }
1334
- .tabs .tab[aria-current] .count { background: var(--primary-soft); color: var(--primary); }
1437
+ .tabs .tab:is(button[aria-current], [aria-current="page"]) .count { background: var(--primary-soft); color: var(--primary); }
1335
1438
 
1336
1439
  /* ---- FilterChips ---- */
1337
1440
  .chips { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
@@ -2165,8 +2268,9 @@ export default function StateBadge({
2165
2268
  "components/Tabs.tsx": `import { Link } from "@ezship/react";
2166
2269
 
2167
2270
  /**
2168
- * A row of tabs. A tab with \`to\` is a link to that route and is current when the route is; the others are
2169
- * buttons, current when their \`value\` is \`value\`, and call \`onChange\`. \`count\` draws a number beside it.
2271
+ * A row of tabs. A tab with \`to\` is a link, current on exactly its route and query (\`/?status=open\`; \`/\` is
2272
+ * the unfiltered one); the others are buttons, current when their \`value\` is \`value\`, and call \`onChange\`.
2273
+ * \`count\` draws a number beside it.
2170
2274
  */
2171
2275
  export default function Tabs({
2172
2276
  tabs,
@@ -2753,6 +2857,7 @@ function resolveRelative(from, specifier) {
2753
2857
  return parts.join("/");
2754
2858
  }
2755
2859
 
2860
+ const LOCAL_IMPORT_SHAPE = `local functions import @ezship/react/local, node:* built-ins, the packages ${LOCAL_PACKAGES_FILE} lists, ${DESKTOP_NATIVE_PACKAGES.join(", ")}, constants, sibling local functions, ../functions/<name> for context.call, and type-only global/db/types.`;
2756
2861
  const IMPORT_SHAPE = `Site code imports only react, @ezship/react, ${SITE_PACKAGES.join(", ")}, global/<Name>, global/documents/<Name>, global/hooks/use<Name>, global/constants, global/lib/<name>, ./constants, ./components/<Name>, ./hooks/use<Name>, ./lib/<name>, ./functions/<name>, ./local/<name> (../constants, ../components/<Name>, ../hooks/use<Name>, ../lib/<name>, ../functions/<name> and ../local/<name> from a page, component or hook), and \`import type\` from global/db/types (no extensions).`;
2757
2862
  /**
2758
2863
  * A component of the Instance's Global Workspace, by its short name or by its path (`global/components/<Name>`,
@@ -2785,10 +2890,19 @@ export function importError(path, specifier, typeOnly, files) {
2785
2890
  if (specifier.startsWith("node:")) return null;
2786
2891
  if (NODE_BUILTINS.has(specifier.split("/")[0]))
2787
2892
  return `"${specifier}": write Node built-ins with the node: prefix (node:${specifier}).`;
2893
+ if (DESKTOP_NATIVE_PACKAGES.includes(specifier)) return null;
2894
+ // A package local/packages.json lists, or one of its files (ADR 0250).
2895
+ const listed = specifier.startsWith("@ezship/") ? null : packageOf(specifier);
2896
+ if (listed !== null)
2897
+ return Object.hasOwn(parseLocalPackages(files[LOCAL_PACKAGES_FILE] ?? "{}").packages, listed)
2898
+ ? null
2899
+ : `"${specifier}": list ${listed} in ${LOCAL_PACKAGES_FILE} with an exact version ({ "${listed}": "1.2.3" }) to import it.`;
2788
2900
  const target = resolveRelative(path, specifier);
2789
2901
  if (target === "constants") return null;
2790
2902
  if (target && localFunctionName(target + ".ts") && target + ".ts" in files) return null;
2791
- 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}`;
2792
2906
  }
2793
2907
  // A Site's own lib module (ADR 0209): a Global lib module's imports, and the constants.
2794
2908
  if (libModuleName(path)) {
@@ -3232,11 +3346,25 @@ export function checkStructure(files) {
3232
3346
  for (const error of listeners.errors) top(LISTENERS_FILE, "listeners", error);
3233
3347
  if (PAGE_FILE in files)
3234
3348
  for (const error of parsePage(files[PAGE_FILE]).errors) top(PAGE_FILE, "page", error);
3349
+ // ADR 0250: local functions' packages, checked as a Push checks them, before any install.
3350
+ if (LOCAL_PACKAGES_FILE in files)
3351
+ for (const error of parseLocalPackages(files[LOCAL_PACKAGES_FILE]).errors)
3352
+ top(LOCAL_PACKAGES_FILE, "local-packages", error);
3235
3353
  for (const warning of listeners.warnings) {
3236
3354
  top(warning.split(" ")[0] ?? LISTENERS_FILE, "listener-unlisted", warning);
3237
3355
  const last = out[out.length - 1];
3238
3356
  if (last) last.severity = 2;
3239
3357
  }
3358
+ // ADR 0250: every running Desktop starts every service, so a Site keeps few.
3359
+ const services = Object.keys(files)
3360
+ .filter((p) => localFunctionName(p) && localKindOf(files[p] ?? "") === "service")
3361
+ .sort();
3362
+ for (const path of services.slice(LOCAL_SERVICE_MAX))
3363
+ top(
3364
+ path,
3365
+ "local-services",
3366
+ `A Site runs at most ${LOCAL_SERVICE_MAX} local services (${services.length} here). Fold ${path}'s work into another service, or make it a local function or stream.`,
3367
+ );
3240
3368
  for (const [path, source] of Object.entries(files)) {
3241
3369
  const bad = siteFileError(path);
3242
3370
  if (bad) {
@@ -3389,7 +3517,7 @@ export const CHECK_RULES = Object.freeze(
3389
3517
  [
3390
3518
  "function-import",
3391
3519
  "error",
3392
- "a function file importing more than its factory, z and types",
3520
+ "a function file importing more than its factory, z, the helpers (today, now, toDate, toEpoch, toCents, fromCents, errorMessage, WriteError) and types",
3393
3521
  'import { serverFunction, z } from "@ezship/react/server"',
3394
3522
  ],
3395
3523
  [
@@ -3421,6 +3549,24 @@ export const CHECK_RULES = Object.freeze(
3421
3549
  ["schedules", "error", "a schedules.json problem", "follow `ez help jobs`"],
3422
3550
  ["listeners", "error", "a listeners.json problem (docs/adr/0231)", "follow `ez help jobs`"],
3423
3551
  ["page", "error", "a page.json problem (docs/adr/0209)", "follow `ez help files`"],
3552
+ [
3553
+ "local-packages",
3554
+ "error",
3555
+ `a ${LOCAL_PACKAGES_FILE} problem: not an object of exact versions, more than ${LOCAL_PACKAGES_MAX} packages, or a package that does not install or needs compiling or an install script (ADR 0250)`,
3556
+ "list exact versions of pure-JavaScript packages; follow `ez help local`",
3557
+ ],
3558
+ [
3559
+ "local-services",
3560
+ "error",
3561
+ `more than ${LOCAL_SERVICE_MAX} local/ files default-export localService (ADR 0250)`,
3562
+ "fold the work into fewer services, or make some local functions or streams",
3563
+ ],
3564
+ [
3565
+ "local-secret-literal",
3566
+ "warning",
3567
+ "a string in local/ that looks like a credential: a known key prefix, a PEM block, or a long random value assigned to a name such as password, secret, token or key (ADR 0250); every Member can read the local artifact",
3568
+ "keep the machine's secret on the machine: an environment variable, or a file under desktop.dataDir",
3569
+ ],
3424
3570
  [
3425
3571
  "listener-unlisted",
3426
3572
  "warning",
@@ -3571,7 +3717,7 @@ export const CHECK_RULES = Object.freeze(
3571
3717
  "table-cast",
3572
3718
  "warning",
3573
3719
  'a cast in a Table argument (name as "orders") or to Query, Insert, Update, Where or Row (docs/adr/0222)',
3574
- "a Table named at run time: db.table(name) or useLive.table(name, query); otherwise a literal name and no cast",
3720
+ "a Table or History named at run time: db.table(name) or useLive.table(name, query); otherwise a literal name and no cast",
3575
3721
  ],
3576
3722
  [
3577
3723
  "query-sentinel",
@@ -3617,7 +3763,8 @@ export function helpRules() {
3617
3763
  CHECK_RULES.filter((r) => r.severity === severity)
3618
3764
  .map((r) => ` ${r.id.padEnd(width)} ${r.summary}\n ${" ".repeat(width)} fix: ${r.fix}`)
3619
3765
  .join("\n");
3620
- return `The rules \`ez check\` runs (the same ones Push, Preview and Deploy run). 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,
3621
3768
  a file and a line, and its message says what to write instead; \`ez check --json\` prints them as
3622
3769
  [{ file, line, column, rule, severity, message }]. No rule sends an edit to apply: make the change the
3623
3770
  message names. Errors fail the check; warnings never do.
@@ -4583,8 +4730,8 @@ db/schema.sql as last pushed) and the live data (the one production App Database
4583
4730
  not types (run ez check first). Members see nothing until ez deploy. Live data: untouched.
4584
4731
  ez global Global: your Global files become the Global Workspace's next Version, after ez global check
4585
4732
  push passes for it and every Site (--force skips that; Admins only). SCHEMA IS PERMANENT HERE:
4586
- published Tables, columns, types, CHECK values, references and indexes can never be renamed
4587
- 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
4588
4735
  new unique index, values a tightened type refuses). Takes effect NOW, for every deployed Site
4589
4736
  and Preview: column defaults, db/access.sql, rules/, workflows/, SINGLETON, EXACTLY ONE OF,
4590
4737
  ON DELETE RESTRICT, session.ts, jobs/ and schedules.json (the push lists them under "Takes
@@ -4915,7 +5062,8 @@ ${GLOBAL_FILES}
4915
5062
  From react: useState, useActionState, useTransition, startTransition, useOptimistic, useMemo, useCallback
4916
5063
  and types. A global component is global/<Name> or, by its path, global/components/<Name>. A page
4917
5064
  imports \`import type { Provided } from "../App"\` for App.tsx's values (ez help frame).
4918
- Server functions (functions/): @ezship/react/server (serverFunction, z and 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
4919
5067
  functions, ../lib/<name>, global/constants, global/lib/<name>, global/documents/<Name> and type-only
4920
5068
  global/db/types.
4921
5069
  Listeners: @ezship/react/server, constants, ../lib/<name>, global/constants, global/lib/<name>, type-only
@@ -4923,8 +5071,9 @@ ${GLOBAL_FILES}
4923
5071
  Site lib (lib/): ${SITE_LIB_IMPORT_SHAPE}
4924
5072
  Global jobs (global/jobs/): @ezship/react/server, global/lib/<name>, global/constants and type-only
4925
5073
  global/db/types; nothing imports a job.
4926
- Local functions (local/): @ezship/react/local, node:* built-ins, constants, sibling local functions and
4927
- 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.
4928
5077
  constants.ts: nothing. Global code: ${GLOBAL_IMPORT_SHAPE}
4929
5078
  Global lib: ${LIB_IMPORT_SHAPE}
4930
5079
  Documents: ${DOCUMENT_IMPORT_SHAPE}
@@ -4937,6 +5086,8 @@ Routes: the page file name is the route. index.tsx is /, orders.tsx is /orders,
4937
5086
  /orders/:id (useParams().id), orders.new.tsx is /orders/new. <Link to="/orders/42">, <Link to="/orders"
4938
5087
  site="kitchen"> (another Site of the Instance), useNavigate()(path), useSites() -> [{ id, name, url, current }].
4939
5088
  A Link to the open route has aria-current="page", to its section aria-current="true": style a[aria-current].
5089
+ A Link whose to names a query (/orders?state=open) is "page" only while the route's query has those values,
5090
+ so link tabs tell views of one route apart; /orders is then "true".
4940
5091
  Styling: className and the Site's style.css, which loads after the Theme (global/style.css). The Theme owns
4941
5092
  the look of every Site, with its tokens:
4942
5093
  ${THEME_TOKENS}
@@ -5204,7 +5355,7 @@ ${snippet("chart")}
5204
5355
  db.insert("orders", { customer, status: "new" }); db.update("orders", id, { status: "ready" }); db.delete("orders", id)
5205
5356
  db.update("orders", id, { status: "paid" }, { why: "Invoice paid by card" }) -> the reason lands in that write's History row
5206
5357
  db.settings("company_settings") -> a SINGLETON Table's row or null
5207
- db.table(name) / useLive.table(name, query | null) / useLive.tableCount(name, query) -> a Table named at run time (no casts)
5358
+ db.table(name) / useLive.table(name, query | null) / useLive.tableCount(name, query) -> a Table or a History (\`\${table}_history\`) named at run time (no casts)
5208
5359
  db.upload("expenses", "receipt", file) -> a FileId for a FILE column (file from <input type="file">); then insert or update with it
5209
5360
  attachment(id) -> that file's URL for <img>, <video> or a download link
5210
5361
  useLive("actors", { where: { id: { in: actorIds } } }) -> { id, kind, name, email }[]: current names for History actor ids
@@ -5570,20 +5721,44 @@ In local/readEmpty.ts:
5570
5721
  });
5571
5722
  UI imports ./local/readEmpty (../local/readEmpty from a page) and calls readEmpty({ path }) from an event
5572
5723
  handler, or useCall(readEmpty, { path }) -> { result, loading, error, refresh } to run it when the page opens.
5573
- A local function has every Node built-in (node:fs, node:path, node:os, node:child_process, node:net, ...),
5574
- the Member (user), the Site (site) and desktop.dataDir, a folder the Desktop keeps for this Site on this
5575
- computer; it has no db: the page saves results with db.insert or a server function.
5576
- [check] Local functions import only @ezship/react/local (localFunction, z and types), node:* built-ins (with
5577
- the prefix), constants, sibling local functions and type-only global/db/types; no packages.
5578
- [runtime] One call runs at most 60 seconds; input, result and errors cross as JSON. It is arbitrary Node code,
5579
- child processes included, on every Member's computer that opens the Site in ezship Desktop, and Members who
5580
- share a computer share its files. In an ordinary browser, the Studio's preview included, a call
5581
- fails and the Framework shows a notice that the app needs ezship Desktop; useDesktop() -> { available,
5582
- version } lets a page offer manual entry instead.
5583
- [advice] Use local functions for station configuration, caches, exports and exchanging files with programs on
5584
- that computer; the App Database stays the shared record, and nothing in a local file is visible to other
5585
- Members or computers. Never write credentials or Host tokens to disk. Test by opening the Preview URL in
5586
- 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).`;
5587
5762
 
5588
5763
  /** `ez help documents` (ADR 0233). */
5589
5764
  const DOCUMENTS_TOPIC = `Documents: PDFs from Global templates in \`global/documents/<Name>.tsx\` (\`ez global put documents/Invoice.tsx\`):
@@ -6461,7 +6636,8 @@ const helpIndex = () => {
6461
6636
  };
6462
6637
 
6463
6638
  /**
6464
- * `ez help [<topic>]`: the onboarding, one topic, or all of them; null 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.
6465
6641
  * @type {typeof import("./commands.d.mts").helpText}
6466
6642
  */
6467
6643
  export function helpText(topic) {
@@ -6473,9 +6649,46 @@ export function helpText(topic) {
6473
6649
  (t) => `==== ez help ${t.name}\n\n${t.text()}`,
6474
6650
  ),
6475
6651
  ].join("\n\n");
6476
- return HELP_TOPICS.find((t) => t.name === topic)?.text() ?? null;
6652
+ return HELP_TOPICS.find((t) => t.name === topic)?.text() ?? commandHelp(topic);
6477
6653
  }
6478
6654
 
6655
+ /**
6656
+ * One command's usage lines (`ez help push`, or `ez push --help`), with `ez global <command>`'s too; null
6657
+ * when no command has that name. A topic of the same name (`ez help db`) comes first.
6658
+ * @param {string} name
6659
+ */
6660
+ function commandHelp(name) {
6661
+ const lines = COMMANDS.filter(isUsageOf(name));
6662
+ return lines.length ? formatHelp(lines) : null;
6663
+ }
6664
+
6665
+ /** Whether a COMMANDS line is `ez <name> ...` or `ez global <name> ...`. @param {string} name */
6666
+ const isUsageOf = (name) => (/** @type {{ usage: string }} */ c) => {
6667
+ const words = c.usage.split(/\s+/);
6668
+ return words[1] === name || (words[1] === "global" && words[2] === name);
6669
+ };
6670
+ /** What every command takes: the output format, the target (read before execute) and --help. */
6671
+ const EVERY_COMMAND_FLAGS = ["--json", "--instance", "--site", "--account", "--help"];
6672
+ /** Flags a command reads that its usage lines leave out. */
6673
+ const MORE_FLAGS = /** @type {Record<string, string[]>} */ ({
6674
+ // push: -m's long form.
6675
+ push: ["--message"],
6676
+ // db: refused by ez db sql itself, with the reason (one App Database for the app and every Preview).
6677
+ db: ["--preview"],
6678
+ });
6679
+ /**
6680
+ * The flags a command takes: those its usage lines name, plus EVERY_COMMAND_FLAGS and MORE_FLAGS.
6681
+ * @param {string} name
6682
+ */
6683
+ const commandFlags = (name) =>
6684
+ new Set([
6685
+ ...COMMANDS.filter(isUsageOf(name)).flatMap((c) => c.usage.match(/--[a-z][a-z0-9-]*/g) ?? []),
6686
+ ...EVERY_COMMAND_FLAGS,
6687
+ ...(MORE_FLAGS[name] ?? []),
6688
+ ]);
6689
+ /** What a flag looks like; other words that start with `--` (an SQL comment) are arguments. */
6690
+ const FLAG_RE = /^--[a-z][a-z0-9-]*$/;
6691
+
6479
6692
  /**
6480
6693
  * Usage + help prose for every `ez` line. `HELP` and `COMMAND_NAMES` are derived from this.
6481
6694
  * @type {typeof import("./commands.d.mts").COMMANDS}
@@ -6530,13 +6743,21 @@ export const COMMANDS = [
6530
6743
  help: "run a command in the Global Working Copy: pull, cat db/types.d.ts, put db/schema.sql, check, push",
6531
6744
  },
6532
6745
  {
6533
- usage: "ez help [<topic> | all]",
6534
- help: "the short guide every task needs; a topic adds detail (lifecycle, files, recipes, data, forms, frame, functions, access, integrations, jobs, api, local, documents, email, db, rules, commands); 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",
6535
6748
  },
6536
6749
  {
6537
6750
  usage: "ez status",
6538
6751
  help: "the shared files' version, what you pulled, your unpushed changes, what deploy would do to the schema and which Global changes it brings in",
6539
6752
  },
6753
+ {
6754
+ usage: "ez diff [<path>]",
6755
+ help: "your Working Copy line by line against the shared files (every file that differs, or one): what a push would change; `ez global diff` for the Global Workspace",
6756
+ },
6757
+ {
6758
+ usage: "ez global starter [<path> | add <path>... [--force]]",
6759
+ help: "your Global Workspace against this CLI's starter (docs/adr/0215): the starter files you lack, the ones that differ, one file's diff; add copies starter files in (--force replaces yours), to check and push like any edit",
6760
+ },
6540
6761
  {
6541
6762
  usage: "ez pull [--force] [--version <n>] [--all]",
6542
6763
  help: "replace the working copy with the shared files (--force overwrites tracked files; untracked files are kept; --version restores a retained Version; --all refreshes every Site from the Instance folder)",
@@ -6790,6 +7011,116 @@ export const COMMAND_NAMES = Object.freeze([
6790
7011
 
6791
7012
  /** @param {string} line */
6792
7013
  const usage = (line) => new Error(`Usage: ${line}`);
7014
+
7015
+ /** A text's lines, without the empty one after a final newline. @param {string} text */
7016
+ const linesOf = (text) => {
7017
+ const lines = text.split("\n");
7018
+ if (lines.at(-1) === "") lines.pop();
7019
+ return lines;
7020
+ };
7021
+ /** Past this many edits a diff says the files differ instead of listing them (Myers keeps one row per edit). */
7022
+ const DIFF_MAX_EDITS = 4000;
7023
+ /**
7024
+ * The edit script from lines `a` to lines `b` (Myers, O((N+M)D)): [" ", line] kept, ["-", line] removed,
7025
+ * ["+", line] added, in order; null past DIFF_MAX_EDITS edits.
7026
+ * @param {string[]} a @param {string[]} b @returns {[" " | "-" | "+", string][] | null}
7027
+ */
7028
+ function lineEdits(a, b) {
7029
+ const n = a.length;
7030
+ const m = b.length;
7031
+ const max = n + m;
7032
+ const v = new Int32Array(2 * max + 2);
7033
+ /** @type {Int32Array[]} */
7034
+ const trace = [];
7035
+ /** @param {Int32Array} row @param {number} k */
7036
+ const at = (row, k) => row[k + max] ?? 0;
7037
+ /** @param {Int32Array} row @param {number} k @param {number} d */
7038
+ const down = (row, k, d) => k === -d || (k !== d && at(row, k - 1) < at(row, k + 1));
7039
+ search: for (let d = 0; d <= max; d++) {
7040
+ if (d > DIFF_MAX_EDITS) return null;
7041
+ trace.push(v.slice());
7042
+ for (let k = -d; k <= d; k += 2) {
7043
+ let x = down(v, k, d) ? at(v, k + 1) : at(v, k - 1) + 1;
7044
+ let y = x - k;
7045
+ while (x < n && y < m && a[x] === b[y]) {
7046
+ x++;
7047
+ y++;
7048
+ }
7049
+ v[k + max] = x;
7050
+ if (x >= n && y >= m) break search;
7051
+ }
7052
+ }
7053
+ /** @type {[" " | "-" | "+", string][]} */
7054
+ const edits = [];
7055
+ let x = n;
7056
+ let y = m;
7057
+ for (let d = trace.length - 1; d >= 0 && (x > 0 || y > 0); d--) {
7058
+ const row = trace[d] ?? v;
7059
+ const k = x - y;
7060
+ const prevK = down(row, k, d) ? k + 1 : k - 1;
7061
+ const prevX = at(row, prevK);
7062
+ const prevY = prevX - prevK;
7063
+ while (x > prevX && y > prevY) {
7064
+ x--;
7065
+ y--;
7066
+ edits.push([" ", a[x] ?? ""]);
7067
+ }
7068
+ if (d === 0) break;
7069
+ if (x === prevX) {
7070
+ y--;
7071
+ edits.push(["+", b[y] ?? ""]);
7072
+ } else {
7073
+ x--;
7074
+ edits.push(["-", a[x] ?? ""]);
7075
+ }
7076
+ }
7077
+ return edits.reverse();
7078
+ }
7079
+ /**
7080
+ * A unified diff (3 lines of context) from `before` to `after`, labelled `from` and `to`; null is a file that
7081
+ * does not exist on that side. Empty when they are equal.
7082
+ * @param {string | null} before @param {string | null} after @param {string} from @param {string} to
7083
+ */
7084
+ function unifiedDiff(before, after, from, to) {
7085
+ if (before === after) return "";
7086
+ const head = [
7087
+ `--- ${before === null ? "/dev/null" : from}`,
7088
+ `+++ ${after === null ? "/dev/null" : to}`,
7089
+ ];
7090
+ const edits = lineEdits(linesOf(before ?? ""), linesOf(after ?? ""));
7091
+ if (!edits) return [...head, "(too different to show line by line)"].join("\n");
7092
+ if (!edits.some(([op]) => op !== " "))
7093
+ return [...head, "(only the final newline differs)"].join("\n");
7094
+ const CONTEXT = 3;
7095
+ /** @type {{ op: string, line: string, i: number, j: number }[]} */
7096
+ const rows = [];
7097
+ let i = 0;
7098
+ let j = 0;
7099
+ for (const [op, line] of edits) {
7100
+ rows.push({ op, line, i, j });
7101
+ if (op !== "+") i++;
7102
+ if (op !== "-") j++;
7103
+ }
7104
+ const changed = (/** @type {number} */ r) => (rows[r]?.op ?? " ") !== " ";
7105
+ const out = [...head];
7106
+ let next = 0;
7107
+ while (next < rows.length) {
7108
+ let start = next;
7109
+ while (start < rows.length && !changed(start)) start++;
7110
+ if (start >= rows.length) break;
7111
+ let end = start;
7112
+ for (let r = start + 1; r < rows.length && r - end <= 2 * CONTEXT; r++) if (changed(r)) end = r;
7113
+ const stop = Math.min(rows.length, end + CONTEXT + 1);
7114
+ const slice = rows.slice(Math.max(next, start - CONTEXT), stop);
7115
+ const old = slice.filter((r) => r.op !== "+").length;
7116
+ const now = slice.filter((r) => r.op !== "-").length;
7117
+ const first = slice[0] ?? { i: 0, j: 0 };
7118
+ out.push(`@@ -${old ? first.i + 1 : first.i},${old} +${now ? first.j + 1 : first.j},${now} @@`);
7119
+ for (const r of slice) out.push(`${r.op}${r.line}`);
7120
+ next = stop;
7121
+ }
7122
+ return out.join("\n");
7123
+ }
6793
7124
  /** "2026-10-11 02:00 UTC": a schedule's due time. @param {number} ms */
6794
7125
  const utcMinute = (ms) => `${new Date(ms).toISOString().slice(0, 16).replace("T", " ")} UTC`;
6795
7126
  /**
@@ -6846,6 +7177,9 @@ export function ago(at) {
6846
7177
  export const pinnedGlobalPath = (path) =>
6847
7178
  path !== SESSION_FILE &&
6848
7179
  path !== SCHEDULES_FILE &&
7180
+ path !== ACCESS_FILE &&
7181
+ ruleTableName(path) === null &&
7182
+ workflowTableName(path) === null &&
6849
7183
  jobName(path) === null &&
6850
7184
  path !== CONTEXT_FILE &&
6851
7185
  docName(path) === null &&
@@ -6853,10 +7187,11 @@ export const pinnedGlobalPath = (path) =>
6853
7187
 
6854
7188
  /**
6855
7189
  * A Global push's two kinds of change (docs/adr/0224): Live ones took effect for every deployed Site at once;
6856
- * the rest reach each Site at its next Preview or Deploy.
6857
- * @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
6858
7193
  */
6859
- function liveLines(result) {
7194
+ function liveLines(result, changed) {
6860
7195
  const lines = [];
6861
7196
  const live = result.live ?? [];
6862
7197
  if (live.length) lines.push("Takes effect now:");
@@ -6927,7 +7262,7 @@ function liveLines(result) {
6927
7262
  }`,
6928
7263
  );
6929
7264
  }
6930
- const pinned = result.written.filter(pinnedGlobalPath);
7265
+ const pinned = (changed ?? result.written).filter(pinnedGlobalPath).sort();
6931
7266
  if (pinned.length)
6932
7267
  lines.push(`Takes effect at each Site's next Preview or Deploy: ${pinned.join(", ")}`);
6933
7268
  return lines;
@@ -7109,6 +7444,10 @@ export function describeCommand(argv) {
7109
7444
  return "Read the instructions";
7110
7445
  case "status":
7111
7446
  return "Checked the site's status";
7447
+ case "diff":
7448
+ return "Compared the working copy with the shared files";
7449
+ case "starter":
7450
+ return a === "add" ? "Copied starter files in" : "Compared with the starter";
7112
7451
  case "pull":
7113
7452
  return "Pulled the site's files";
7114
7453
  case "push":
@@ -7371,6 +7710,23 @@ async function execute(ws, argv, stdin) {
7371
7710
  }
7372
7711
  const flags = new Set(args.filter((a) => a.startsWith("--")));
7373
7712
  const pos = args.filter((a) => !a.startsWith("--"));
7713
+ // --help, and a flag the command does not take, never run it: an ignored flag ran the command as if it were
7714
+ // absent (`ez push --help` pushed, `ez global push --dryrun` would push for real).
7715
+ if ((COMMAND_NAMES.includes(cmd) || COMMANDS.some(isUsageOf(cmd))) && cmd !== "help") {
7716
+ if (flags.has("--help") || args.includes("-h")) {
7717
+ const text = commandHelp(cmd) ?? HELP;
7718
+ return out(text, { usage: text });
7719
+ }
7720
+ const known = commandFlags(cmd);
7721
+ const unknown = [...flags].filter((f) => FLAG_RE.test(f) && !known.has(f));
7722
+ // ez db sql refuses its own stray flags, saying to quote the statement.
7723
+ if (unknown.length && !(cmd === "db" && pos[0] === "sql"))
7724
+ throw usage(
7725
+ `${COMMANDS.filter(isUsageOf(cmd))
7726
+ .map((c) => c.usage)
7727
+ .join("\n ")}\nez ${cmd} takes no ${unknown.join(", ")}, so nothing was run.`,
7728
+ );
7729
+ }
7374
7730
  // The Global Workspace is pushed, pulled and edited like a Site, and nothing else: it has no app, no
7375
7731
  // database of its own, no settings, no members. Global Check validates its schema, Rules and types.
7376
7732
  const global = ws.target?.site === GLOBAL_ID;
@@ -7556,11 +7912,106 @@ async function execute(ws, argv, stdin) {
7556
7912
  const text = helpText(pos[0]);
7557
7913
  if (text === null)
7558
7914
  throw new Error(
7559
- `No help topic "${pos[0]}". Topics: ${HELP_TOPICS.map((t) => t.name).join(", ")}, all.`,
7915
+ `No help topic or command "${pos[0]}". Topics: ${HELP_TOPICS.map((t) => t.name).join(", ")}, all; commands: ez help commands.`,
7560
7916
  );
7561
7917
  return out(text, { instructions: text });
7562
7918
  }
7563
7919
 
7920
+ case "diff": {
7921
+ if (pos.length > 1) throw usage("ez diff [<path>]");
7922
+ const [local, shared] = await Promise.all([ws.files(), ws.fetchAll()]);
7923
+ const at = shared.version.n;
7924
+ const prefix = global ? `${GLOBAL_ID}/` : "";
7925
+ const [one] = pos;
7926
+ if (one !== undefined && !(one in local) && !(one in shared.files))
7927
+ throw new Error(`${one} is in neither your Working Copy nor the shared files (v${at}).`);
7928
+ const paths = (
7929
+ one !== undefined
7930
+ ? [one]
7931
+ : [...new Set([...Object.keys(local), ...Object.keys(shared.files)])]
7932
+ )
7933
+ .filter((p) => local[p] !== shared.files[p])
7934
+ .sort();
7935
+ const diffs = paths.map((p) =>
7936
+ unifiedDiff(
7937
+ shared.files[p] ?? null,
7938
+ local[p] ?? null,
7939
+ `shared v${at} ${prefix}${p}`,
7940
+ `working copy ${prefix}${p}`,
7941
+ ),
7942
+ );
7943
+ if (!diffs.length)
7944
+ return out(
7945
+ `${one === undefined ? "Your Working Copy is" : `${prefix}${one} is`} the same as the shared files (v${at}).`,
7946
+ { version: at, changed: [] },
7947
+ );
7948
+ return out(diffs.join("\n"), { version: at, changed: paths });
7949
+ }
7950
+
7951
+ // The starter (docs/adr/0215) is copied in once; a later one reaches an Instance only by hand, so this
7952
+ // says what differs and copies a file in on request. Only the Global Workspace has one.
7953
+ case "starter": {
7954
+ if (!global)
7955
+ throw new Error(
7956
+ "The starter is the Global Workspace's: run `ez global starter` in a Site's folder.",
7957
+ );
7958
+ const local = await ws.files();
7959
+ const starter = STARTER_GLOBAL_FILES;
7960
+ const isStarter = (/** @type {string} */ p) => Object.hasOwn(starter, p);
7961
+ if (pos[0] === "add") {
7962
+ const paths = pos.slice(1);
7963
+ if (!paths.length) throw usage("ez global starter add <path>... [--force]");
7964
+ for (const p of paths) {
7965
+ if (!isStarter(p))
7966
+ throw new Error(`${p} is not a starter file. \`ez global starter\` lists them.`);
7967
+ if (p in local && local[p] !== starter[p] && !flags.has("--force"))
7968
+ throw new Error(
7969
+ `${GLOBAL_ID}/${p} differs from the starter's: see \`ez global starter ${p}\`, and add --force to replace yours. Nothing was copied.`,
7970
+ );
7971
+ }
7972
+ for (const p of paths) await ws.write(p, starter[p] ?? "");
7973
+ return out(
7974
+ `Copied ${paths.map((p) => `${GLOBAL_ID}/${p}`).join(", ")} from the starter. Run \`ez global check\`, then \`ez global push\` to share ${paths.length === 1 ? "it" : "them"}.`,
7975
+ { copied: paths },
7976
+ );
7977
+ }
7978
+ if (pos.length > 1) throw usage("ez global starter [<path> | add <path>... [--force]]");
7979
+ const [one] = pos;
7980
+ if (one !== undefined) {
7981
+ if (!isStarter(one))
7982
+ throw new Error(`${one} is not a starter file. \`ez global starter\` lists them.`);
7983
+ const diff = unifiedDiff(
7984
+ starter[one] ?? "",
7985
+ local[one] ?? null,
7986
+ `starter ${one}`,
7987
+ `${GLOBAL_ID}/${one}`,
7988
+ );
7989
+ return out(diff || `${GLOBAL_ID}/${one} is the starter's.`, {
7990
+ path: one,
7991
+ same: !diff,
7992
+ missing: !(one in local),
7993
+ });
7994
+ }
7995
+ const all = Object.keys(starter).sort();
7996
+ const missing = all.filter((p) => !(p in local));
7997
+ const differs = all.filter((p) => p in local && local[p] !== starter[p]);
7998
+ const same = all.length - missing.length - differs.length;
7999
+ const lines = [
8000
+ `The starter has ${plural(all.length, "file")}; ${same} of yours ${same === 1 ? "is" : "are"} the same.`,
8001
+ ];
8002
+ if (missing.length)
8003
+ lines.push(
8004
+ `Not in your Global (copy one in with \`ez global starter add <path>\`):`,
8005
+ ...missing.map((p) => ` ${p}`),
8006
+ );
8007
+ if (differs.length)
8008
+ lines.push(
8009
+ `Differ from the starter (see one with \`ez global starter <path>\`):`,
8010
+ ...differs.map((p) => ` ${p}`),
8011
+ );
8012
+ return out(lines.join("\n"), { missing, differs, same });
8013
+ }
8014
+
7564
8015
  case "status": {
7565
8016
  const [remote, files, pulled] = await Promise.all([
7566
8017
  ws.remoteStatus(),
@@ -7708,9 +8159,19 @@ async function execute(ws, argv, stdin) {
7708
8159
  if (global && flags.has("--dry-run")) options.dryRun = true;
7709
8160
  if (global && flags.has("--acknowledge-exposure")) options.acknowledgeExposure = true;
7710
8161
  if (global && flags.has("--force")) options.force = true;
8162
+ // What this push changes, to say what waits for each Site: a push sends every file, so compare with the
8163
+ // published Version rather than list them all.
8164
+ const published = global ? await ws.fetchAll().catch(() => null) : null;
8165
+ const changed = published?.files
8166
+ ? Object.keys(files).filter((p) => published.files[p] !== files[p])
8167
+ : null;
7711
8168
  const result = await ws.pushAll(files, flags.has("--prune"), deleted, options);
7712
8169
  if (result.dryRun) {
7713
- const dry = ["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
+ ];
7714
8175
  return out(dry.join("\n"), result);
7715
8176
  }
7716
8177
  await ws.setPulled({ version: result.version, hashes: hashAll(files) });
@@ -7718,7 +8179,7 @@ async function execute(ws, argv, stdin) {
7718
8179
  `Pushed ${plural(result.written.length, "file")} (${versionLine(result.version)}). ${global ? "Schema names and types are now permanent; Sites receive additions on their next Preview or Deploy." : "Run `ez deploy` to publish."}`,
7719
8180
  ];
7720
8181
  for (const p of result.deleted) lines.push(`deleted ${p}`);
7721
- if (global) lines.push(...liveLines(result), ...reportLines(result));
8182
+ if (global) lines.push(...liveLines(result, changed), ...reportLines(result));
7722
8183
  return out(lines.join("\n"), result);
7723
8184
  }
7724
8185
 
@@ -9061,7 +9522,7 @@ async function execute(ws, argv, stdin) {
9061
9522
  const lines = [];
9062
9523
  for (const t of tables) {
9063
9524
  lines.push(
9064
- `${t.name} ${plural(t.rows, "row")}${t.history ? ` the History of ${t.history} (read-only)` : ""}`,
9525
+ `${t.name} ${plural(t.rows, "row")}${t.history ? ` the History of ${t.history} (read-only)` : ""}${t.ruled ? " Table rules (ez db sql skips them)" : ""}`,
9065
9526
  );
9066
9527
  for (const [c, d] of Object.entries(t.columns)) lines.push(` ${c} ${d}`);
9067
9528
  for (const cols of t.indexes) lines.push(` index (${cols.join(", ")})`);
@@ -9083,7 +9544,14 @@ async function execute(ws, argv, stdin) {
9083
9544
  const statement = (pos.slice(1).join(" ") || stdin || "").trim();
9084
9545
  if (!statement) throw usage("ez db sql <statement> (or pipe the statement on stdin)");
9085
9546
  const r = await ws.dbSql(statement);
9086
- if ("changed" in r) 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
+ }
9087
9555
  const cols = r.rows.length ? Object.keys(r.rows[0]) : [];
9088
9556
  const lines = [cols.join("\t")];
9089
9557
  for (const row of r.rows) lines.push(cols.map((c) => cellText(row[c])).join("\t"));
package/connections.mjs CHANGED
@@ -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.17",
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/paths.d.mts CHANGED
@@ -11,6 +11,8 @@ export const ACCESS_RULES_PATH: "/_ez/access";
11
11
  /** The active scope's values for the Framework's switcher (docs/adr/0225). */
12
12
  export const SCOPE_PATH: "/_ez/scope";
13
13
  export const VERSIONS_HEADER: "ez-versions";
14
+ /** A Preview page's first screen is complete (docs/adr/0212): the app host's swap shows it then. */
15
+ export const FIRST_SCREEN_EVENT: "ez:first-screen";
14
16
  /** Session State (docs/adr/0214): the page's path and the viewer's own counter in the live version map. */
15
17
  export const SESSION_PATH: "/_ez/session";
16
18
  export const SESSION_VERSION_KEY: "~session";
package/paths.mjs CHANGED
@@ -37,6 +37,14 @@ export const SCOPE_PATH = "/_ez/scope";
37
37
  */
38
38
  export const VERSIONS_HEADER = "ez-versions";
39
39
 
40
+ /**
41
+ * The window event a Preview page's Framework dispatches once, when its first screen is complete (docs/adr/0212):
42
+ * the Shell and the page have committed and no request of the Framework's has been in flight for a moment. The
43
+ * app host's swap holds the last build's screen over the page until it.
44
+ * @type {typeof import("./paths.d.mts").FIRST_SCREEN_EVENT}
45
+ */
46
+ export const FIRST_SCREEN_EVENT = "ez:first-screen";
47
+
40
48
  /** Where a page reads (GET) and writes (PUT `/<key>`) its viewer's Session State, under the Site's prefix. */
41
49
  export const SESSION_PATH = "/_ez/session";
42
50
  /** The viewer's own counter in the live version map (docs/adr/0220); no Table can have this name. */
package/schema.d.mts CHANGED
@@ -295,12 +295,21 @@ export function checkSql(
295
295
  instance: string,
296
296
  ):
297
297
  | { kind: "read"; sql: string; tables: string[] }
298
- | { 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. */