ezship 0.1.13 → 0.1.15

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
@@ -41,6 +41,7 @@ import type {
41
41
  DeployResult,
42
42
  FormatResult,
43
43
  FunctionResult,
44
+ GlobalSinceDeploy,
44
45
  RenderRequest,
45
46
  RenderRow,
46
47
  InstanceInfo,
@@ -377,12 +378,12 @@ export const LISTENER_MAX: number;
377
378
  export const LISTENER_BASE_PATH: "/_ez/listeners/";
378
379
  export const WEBHOOK_SCHEMES: readonly ["standard", "stripe", "github", "token"];
379
380
  export const LISTENER_OVERLAP_HOURS: { readonly default: number; readonly max: number };
380
- /** The Site API (docs/adr/0119): `<prefix>/_ez/api/...` with `Authorization: Bearer ezk_...`. */
381
+ /** The Data API (docs/adr/0151): `/_ez/api/...` on the app origin with `Authorization: Bearer ezk_...`. */
381
382
  export const API_BASE_PATH: "/_ez/api";
382
383
  export const API_KEY_PREFIX: "ezk_";
383
384
  export const API_KEY_NAME_RE: RegExp;
384
385
  export const API_KEY_DAYS: { readonly default: number; readonly max: number };
385
- export const API_KEYS_PER_SITE: number;
386
+ export const API_KEYS_PER_INSTANCE: number;
386
387
  export const API_KEY_RATE: { readonly burst: number; readonly perSecond: number };
387
388
  export const LISTENER_BODY_MAX: number;
388
389
  /** The entries of a listeners.json, every problem with it, and the listeners/ files it does not name. */
@@ -630,6 +631,21 @@ export const AUTH_PATH: string;
630
631
 
631
632
  export function hashContent(s: string): string;
632
633
  export function localChanges(files: Record<string, string>, pulled: Pulled | null): Changes;
634
+ /**
635
+ * Whether a change to this Global Workspace file reaches a deployed Site only at its next Preview or Deploy
636
+ * (docs/adr/0096): false for the Live-only files (session.ts, schedules.json, jobs/) and the files no app is
637
+ * built from (CONTEXT.md, docs/, the generated db/types.d.ts).
638
+ */
639
+ export function pinnedGlobalPath(path: string): boolean;
640
+ /**
641
+ * What the Site's next deploy brings in from the Global Workspace (`site` is its remoteStatus, `global` the
642
+ * Global Workspace): null when the Site has no recorded deploy or the Host does not say which Global Version
643
+ * it built in.
644
+ */
645
+ export function globalSinceDeploy(
646
+ site: WorkspaceInfo,
647
+ global: Workspace,
648
+ ): Promise<GlobalSinceDeploy | null>;
633
649
  export function countChanges(c: Changes): number;
634
650
  export function ago(at: number | null | undefined): string;
635
651
 
package/commands.mjs CHANGED
@@ -227,21 +227,21 @@ export const LISTENER_OVERLAP_HOURS = Object.freeze({ default: 24, max: 168 });
227
227
  /** @type {typeof import("./commands.d.mts").LISTENER_BODY_MAX} */
228
228
  export const LISTENER_BODY_MAX = 256_000;
229
229
  /**
230
- * The Site API (docs/adr/0119): other systems reach a Site's data under `<prefix>/_ez/api/` with an API Key,
231
- * `Authorization: Bearer ezk_...`, before the Member gate.
230
+ * The Data API (docs/adr/0119, docs/adr/0151): other systems reach an Instance's data under `/_ez/api/` on its
231
+ * app origin with an API Key, `Authorization: Bearer ezk_...`.
232
232
  * @type {typeof import("./commands.d.mts").API_BASE_PATH}
233
233
  */
234
234
  export const API_BASE_PATH = "/_ez/api";
235
235
  /** @type {typeof import("./commands.d.mts").API_KEY_PREFIX} */
236
236
  export const API_KEY_PREFIX = "ezk_";
237
- /** An API Key's name: permanent on its Site, the `<name>` of its actor `key:<site>/<name>`. */
237
+ /** An API Key's name: permanent on its Instance, the `<name>` of its actor `key:<name>`. */
238
238
  /** @type {typeof import("./commands.d.mts").API_KEY_NAME_RE} */
239
239
  export const API_KEY_NAME_RE = /^[a-z][a-z0-9-]{0,39}$/;
240
240
  /** How long a new API Key lasts, in days. */
241
241
  /** @type {typeof import("./commands.d.mts").API_KEY_DAYS} */
242
242
  export const API_KEY_DAYS = Object.freeze({ default: 90, max: 365 });
243
- /** @type {typeof import("./commands.d.mts").API_KEYS_PER_SITE} */
244
- export const API_KEYS_PER_SITE = 20;
243
+ /** @type {typeof import("./commands.d.mts").API_KEYS_PER_INSTANCE} */
244
+ export const API_KEYS_PER_INSTANCE = 50;
245
245
  /** Each key's token bucket on the door: `burst` requests, refilled at `perSecond`. */
246
246
  /** @type {typeof import("./commands.d.mts").API_KEY_RATE} */
247
247
  export const API_KEY_RATE = Object.freeze({ burst: 120, perSecond: 20 });
@@ -3920,12 +3920,12 @@ export const ROUTES = Object.freeze({
3920
3920
  path: `${SITE}/listeners/:name/events/:id/retry`,
3921
3921
  args: (name, id) => ({ params: { name, id } }),
3922
3922
  },
3923
- // API Keys (docs/adr/0119): Admins create and revoke them; every Builder of the Site lists them.
3924
- listApiKeys: { method: "GET", path: `${SITE}/keys` },
3925
- createApiKey: { method: "POST", path: `${SITE}/keys`, args: (input) => body(input) },
3923
+ // API Keys (docs/adr/0119, docs/adr/0151): the Instance's; Admins create and revoke, every Builder lists.
3924
+ listApiKeys: { method: "GET", path: `${INSTANCE}/keys` },
3925
+ createApiKey: { method: "POST", path: `${INSTANCE}/keys`, args: (input) => body(input) },
3926
3926
  revokeApiKey: {
3927
3927
  method: "DELETE",
3928
- path: `${SITE}/keys/:name`,
3928
+ path: `${INSTANCE}/keys/:name`,
3929
3929
  args: (name) => ({ params: { name } }),
3930
3930
  },
3931
3931
  callFunction: {
@@ -4458,6 +4458,8 @@ How to work
4458
4458
  6. \`ez preview\` (or \`ez dev\`, which keeps it current) and give the user \`ez link --preview <name>\`;
4459
4459
  a successful preview is also a check. Its data is the live data.
4460
4460
  7. Keep CONTEXT.md and the docs current, \`ez pull\`, \`ez push -m "<what it is for>"\`, and \`ez deploy\` once the user agrees.
4461
+ Before you ask, \`ez status\`: its "global:" line names the Global changes pushed since the live app
4462
+ was built, which the deploy brings in too; name them to the user.
4461
4463
  Ask the user before \`ez deploy\` and before every App Database write: \`ez db sql\` INSERT, UPDATE or DELETE,
4462
4464
  \`ez db attach\`, \`ez db redact\` and \`ez function call\`. \`ez check\`, \`ez format\` and \`ez preview\` are free
4463
4465
  to run. When ezship itself fails (a command errors in a way no change to the code fixes, or the platform does
@@ -4777,31 +4779,35 @@ conversation); until then every delivery is refused.
4777
4779
  effect on the payload's own id with a unique index, and pass event.deliveryId to services as the idempotency
4778
4780
  key. \`ez listener events <name> [--dead]\`, \`show\` and \`retry\` inspect and replay events.`;
4779
4781
 
4780
- /** `ez help api`: the Site API and its API Keys (docs/adr/0119). */
4781
- const API_TOPIC = `The Site API lets another system (a sync job, a reporting tool, a script on the customer's server) read
4782
- and write this Site's data over HTTPS. Pages never use it: they have useLive and db.
4783
- An Admin creates an API Key in a terminal: \`ez key create warehouse --groups warehouse [--expires <days>]\`
4784
- prints the key (${API_KEY_PREFIX}...) once; give it to the other system as a secret, never through this conversation
4785
- or in Site code. \`ez key list\` shows every key (never the key itself), \`ez key revoke <name>\` ends one.
4786
- [runtime] A key acts as its own principal, key:<site>/<name>, decided as an active Member who holds only the
4782
+ /** `ez help api`: the Data API and its API Keys (docs/adr/0119, docs/adr/0151). */
4783
+ const API_TOPIC = `The Data API lets another system (a sync job, a reporting tool, a script on the customer's server) read
4784
+ and write this Instance's data over HTTPS. Pages never use it: they have useLive and db.
4785
+ An Admin creates an API Key in a terminal, from any Working Copy of the Instance: \`ez key create warehouse
4786
+ --groups warehouse [--sites <all | ids>] [--expires <days>]\` prints the key (${API_KEY_PREFIX}...) once; give it to the
4787
+ other system as a secret, never through this conversation or in Site code. \`ez key list\` shows every key
4788
+ (never the key itself), \`ez key revoke <name>\` ends one. A key's groups and Sites are fixed when it is created.
4789
+ [runtime] A key acts as its own principal, key:<name>, decided as an active Member who holds only the
4787
4790
  key's groups (and those they imply) and no MEMBER identity: global/db/access.sql applies with its row
4788
4791
  conditions, owner is the rows the key wrote, "= me" never matches, BY functions and BY none refuse its
4789
4792
  writes, and rules, workflows, defaults and History run as for a page. Give access by group:
4790
4793
  GROUP warehouse;
4791
4794
  READ orders WHERE group(warehouse) OR owner;
4792
- Requests go to <app url>/_ez/api/... with "Authorization: Bearer <key>" and JSON bodies; a browser's
4795
+ Requests go to <app origin>/_ez/api/... with "Authorization: Bearer <key>" and JSON bodies; a browser's
4793
4796
  request (one with an Origin header) is refused. GET _ez/api says who the key is; GET _ez/api/openapi.json
4794
- describes what it may reach. _ez/api/db/<table> is the page's data API: POST <table>/query, POST
4797
+ describes what it may reach. It serves the published schema as far as the App Database holds it: a Table or
4798
+ column is there once a Preview or Deploy has created it. _ez/api/db/<table> is the page's data API: POST <table>/query, POST
4795
4799
  <table>/aggregate, GET <table>/<id>, POST <table> (insert), PATCH and DELETE <table>/<id>, POST
4796
4800
  <table>/<id>/actions/<action>; ?why= gives a write its reason. The change feed is the History:
4797
4801
  POST _ez/api/db/<table>_history/query {"where":{"version":{"gt":<last seen>}},"order":["version"]}.
4798
4802
  Server functions are callable by a key only when they say so: serverFunction(input, handler, { api: true })
4799
- [check: function-options]; POST _ez/api/functions/<name> {"input": ...} answers {"result": ...}, against the
4800
- deployed Site, under the function's own access and authority. In the handler a key's user is
4801
- { id: "key:<site>/<name>", email: "", name, me: null, groups }. Files: POST
4803
+ [check: function-options], and only on the Sites its --sites allows. [runtime] Without --sites a key calls no
4804
+ functions, all means every unrestricted Site, and a Restricted Site is reached only by a key that names its id;
4805
+ --sites never narrows data, which groups do. POST _ez/api/sites/<site>/functions/<name> {"input": ...} answers
4806
+ {"result": ...}, against that Site's deployed artifact, under the function's own access and authority. In the
4807
+ handler a key's user is { id: "key:<name>", email: "", name, me: null, groups }. Files: POST
4802
4808
  _ez/api/attachments/<table>/<column>?name=<file> with the bytes, GET _ez/api/attachments/<id>.
4803
4809
  [runtime] Each key may make ${API_KEY_RATE.burst} requests at once, refilled at ${API_KEY_RATE.perSecond} a second (429 with Retry-After
4804
- past that). A key lasts ${API_KEY_DAYS.default} days by default, at most ${API_KEY_DAYS.max}; a Site holds at most ${API_KEYS_PER_SITE} active keys. A
4810
+ past that). A key lasts ${API_KEY_DAYS.default} days by default, at most ${API_KEY_DAYS.max}; an Instance holds at most ${API_KEYS_PER_INSTANCE} active keys. A
4805
4811
  name is never reused: to rotate, create a new key, switch the other system to it, revoke the old one.
4806
4812
  Previews have no API.`;
4807
4813
 
@@ -5381,7 +5387,7 @@ export const HELP_TOPICS = Object.freeze([
5381
5387
  },
5382
5388
  {
5383
5389
  name: "api",
5384
- summary: "the Site API: API Keys that let other systems read and write this Site's data",
5390
+ summary: "the Data API: API Keys that let other systems read and write this Instance's data",
5385
5391
  text: () => API_TOPIC,
5386
5392
  },
5387
5393
  {
@@ -5507,7 +5513,7 @@ export const COMMANDS = [
5507
5513
  },
5508
5514
  {
5509
5515
  usage: "ez status",
5510
- help: "the shared files' version, what you pulled, your unpushed changes, what deploy would do to the schema",
5516
+ 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",
5511
5517
  },
5512
5518
  {
5513
5519
  usage: "ez pull [--force] [--version <n>] [--all]",
@@ -5515,7 +5521,7 @@ export const COMMANDS = [
5515
5521
  },
5516
5522
  {
5517
5523
  usage: 'ez push [-m "<message>"] [--prune] [--force] [--dry-run] [--acknowledge-exposure]',
5518
- help: "replace the shared files with the working copy, deleting the pulled files you removed (--prune also deletes shared files this copy never pulled); -m says what the push is for, shown by ez versions; in <instance>/global, the Global Workspace's, after `ez global check` passes for it and every Site (--force skips that; admins only); a global push lists what takes effect now (defaults, access rules, session.ts, rules), --dry-run shows that and each changed rule's effect without pushing, --acknowledge-exposure accepts access rules that let Members read more",
5524
+ help: "replace the shared files with the working copy, deleting the pulled files you removed (--prune also deletes shared files this copy never pulled); -m says what the push is for, shown by ez versions; in <instance>/global, the Global Workspace's, after `ez global check` passes for it and every Site (--force skips that; admins only); a global push lists what takes effect now (defaults, access rules, session.ts, rules), --dry-run shows that and each changed rule's effect without pushing (a Site push refuses it), --acknowledge-exposure accepts access rules that let Members read more",
5519
5525
  },
5520
5526
  { usage: "ez deploy", help: "ship the shared files to the live app" },
5521
5527
  {
@@ -5730,11 +5736,11 @@ export const COMMANDS = [
5730
5736
  },
5731
5737
  {
5732
5738
  usage: "ez key list",
5733
- help: "this site's API Keys: name, groups, state, expiry and last use, never the key (ez help api)",
5739
+ help: "this instance's API Keys: name, groups, sites, state, expiry and last use, never the key (ez help api)",
5734
5740
  },
5735
5741
  {
5736
- usage: "ez key create <name> [--groups <a,b>] [--expires <days>]",
5737
- help: "admins: an API Key another system uses to reach this site's data; printed once",
5742
+ usage: "ez key create <name> [--groups <a,b>] [--sites <all | ids>] [--expires <days>]",
5743
+ help: "admins: an API Key another system uses to reach this instance's data; printed once",
5738
5744
  },
5739
5745
  {
5740
5746
  usage: "ez key revoke <name>",
@@ -5820,6 +5826,15 @@ export function ago(at) {
5820
5826
  return `${Math.round(s / 86400)}d ago`;
5821
5827
  }
5822
5828
 
5829
+ /** @type {typeof import("./commands.d.mts").pinnedGlobalPath} */
5830
+ export const pinnedGlobalPath = (path) =>
5831
+ path !== SESSION_FILE &&
5832
+ path !== SCHEDULES_FILE &&
5833
+ jobName(path) === null &&
5834
+ path !== CONTEXT_FILE &&
5835
+ docName(path) === null &&
5836
+ path !== TYPES_FILE;
5837
+
5823
5838
  /**
5824
5839
  * A Global push's two kinds of change (docs/adr/0096): Live ones took effect for every deployed Site at once;
5825
5840
  * the rest reach each Site at its next Preview or Deploy.
@@ -5896,9 +5911,7 @@ function liveLines(result) {
5896
5911
  }`,
5897
5912
  );
5898
5913
  }
5899
- const pinned = result.written.filter(
5900
- (p) => p !== SESSION_FILE && p !== SCHEDULES_FILE && !jobName(p),
5901
- );
5914
+ const pinned = result.written.filter(pinnedGlobalPath);
5902
5915
  if (pinned.length)
5903
5916
  lines.push(`Takes effect at each Site's next Preview or Deploy: ${pinned.join(", ")}`);
5904
5917
  return lines;
@@ -6008,6 +6021,59 @@ async function schemaStatus(ws, files, instance, siteId) {
6008
6021
  return { lines, data: { ok: true, created, added, indexed, conflicts: plan.conflicts } };
6009
6022
  }
6010
6023
 
6024
+ /**
6025
+ * What the Site's next deploy brings in from the Global Workspace (docs/adr/0141): the pushed Global files that
6026
+ * changed since the Version its live app was built with, as the Host recorded that deploy. A deploy builds the
6027
+ * pushed Global, so unpushed Global changes are not among them.
6028
+ * @type {typeof import("./commands.d.mts").globalSinceDeploy}
6029
+ */
6030
+ export async function globalSinceDeploy(site, global) {
6031
+ const deployed = site.deployedGlobal;
6032
+ if (site.deployedAt === null || typeof deployed !== "number") return null;
6033
+ const newest = (await global.remoteStatus()).version.n;
6034
+ if (newest <= deployed)
6035
+ return { deployed, current: newest, paths: { added: [], changed: [], removed: [] } };
6036
+ const [before, after] = await Promise.all([
6037
+ deployed === 0
6038
+ ? { files: /** @type {Record<string, string>} */ ({}) }
6039
+ : global.fetchAll(deployed).catch(() => null),
6040
+ global.fetchAll(),
6041
+ ]);
6042
+ const current = after.version.n;
6043
+ if (!before) return { deployed, current, paths: null };
6044
+ const was = before.files;
6045
+ const now = after.files;
6046
+ /** @param {string[]} paths */
6047
+ const pinned = (paths) => paths.filter(pinnedGlobalPath).sort();
6048
+ return {
6049
+ deployed,
6050
+ current,
6051
+ paths: {
6052
+ added: pinned(Object.keys(now).filter((p) => !(p in was))),
6053
+ changed: pinned(Object.keys(now).filter((p) => p in was && was[p] !== now[p])),
6054
+ removed: pinned(Object.keys(was).filter((p) => !(p in now))),
6055
+ },
6056
+ };
6057
+ }
6058
+
6059
+ /**
6060
+ * `ez status`'s Global line: what a deploy brings in from the Global Workspace.
6061
+ * @param {import("./types.d.mts").GlobalSinceDeploy} g
6062
+ */
6063
+ function globalStatusLine(g) {
6064
+ const live = `the live app was built with Global v${g.deployed}`;
6065
+ if (!g.paths)
6066
+ return `global: deploy would bring in Global v${g.current} (${live}, no longer retained, so its changes cannot be listed)`;
6067
+ const { added, changed, removed } = g.paths;
6068
+ if (added.length + changed.length + removed.length === 0)
6069
+ return `global: up to date (${live}${g.current > g.deployed ? `; v${g.current} changed nothing a deploy brings in` : ""})`;
6070
+ const parts = [];
6071
+ if (added.length) parts.push(`added ${added.join(", ")}`);
6072
+ if (changed.length) parts.push(`changed ${changed.join(", ")}`);
6073
+ if (removed.length) parts.push(`removed ${removed.join(", ")}`);
6074
+ return `global: deploy would bring in Global v${g.current} (${live}): ${parts.join("; ")}`;
6075
+ }
6076
+
6011
6077
  /**
6012
6078
  * A short human label for a command, for the chat UI ("Read index.html"). Never shows the argv itself.
6013
6079
  * @type {typeof import("./commands.d.mts").describeCommand}
@@ -6310,7 +6376,7 @@ function integrationLines(i) {
6310
6376
  * @param {string} cmd @param {string[]} pos
6311
6377
  */
6312
6378
  const GLOBAL_REFUSES = (cmd, pos) =>
6313
- ["deploy", "preview", "link", "config", "function", "listener", "key"].includes(cmd) ||
6379
+ ["deploy", "preview", "link", "config", "function", "listener"].includes(cmd) ||
6314
6380
  (cmd === "site" && pos[0] === "access");
6315
6381
 
6316
6382
  /** @param {Workspace} ws @param {string[]} argv @param {string} [stdin] @returns {Promise<{text: string, data: unknown}>} */
@@ -6515,6 +6581,14 @@ async function execute(ws, argv, stdin) {
6515
6581
  ? null
6516
6582
  : await schemaStatus(ws, (await ws.globalFiles?.()) ?? {}, remote.instance, remote.id);
6517
6583
  if (schema) lines.push(...schema.lines);
6584
+ // What the deploy also brings in from the Global Workspace (docs/adr/0141); never fails the status.
6585
+ const brings = global
6586
+ ? null
6587
+ : await (async () => {
6588
+ const g = await ws.globalWorkspace?.();
6589
+ return g ? globalSinceDeploy(remote, g) : null;
6590
+ })().catch(() => null);
6591
+ if (brings) lines.push(globalStatusLine(brings));
6518
6592
  return out(lines.join("\n"), {
6519
6593
  site: { instance: remote.instance, id: remote.id, name: remote.name },
6520
6594
  version: remote.version,
@@ -6524,6 +6598,7 @@ async function execute(ws, argv, stdin) {
6524
6598
  behind: !!(pulled && remote.version.n > pulled.version.n),
6525
6599
  changes,
6526
6600
  schema: schema?.data ?? null,
6601
+ global: brings,
6527
6602
  });
6528
6603
  }
6529
6604
 
@@ -6588,6 +6663,12 @@ async function execute(ws, argv, stdin) {
6588
6663
  throw usage('ez push [-m "<message>"] [--prune] [--force]');
6589
6664
  const checked = messageText(message, "The message");
6590
6665
  if ("error" in checked) throw new Error(checked.error);
6666
+ // --dry-run reports a Global push's Live changes (docs/adr/0096). A Site push has none, and ignoring the
6667
+ // flag would push for real, so it is refused before anything is sent.
6668
+ if (!global && flags.has("--dry-run"))
6669
+ throw new Error(
6670
+ "--dry-run is for the Global Workspace (ez global push --dry-run); here it would push for real. Nothing was pushed. Run ez status to see what a push sends.",
6671
+ );
6591
6672
  const files = await ws.files();
6592
6673
  if (global && SCHEMA_FILE in files) await regenerateTypes(ws, SCHEMA_FILE);
6593
6674
  await regenerateInventory(ws);
@@ -7746,10 +7827,10 @@ async function execute(ws, argv, stdin) {
7746
7827
  }
7747
7828
 
7748
7829
  case "key": {
7749
- // docs/adr/0119: an API Key is shown once, by create, and never again.
7830
+ // docs/adr/0119, docs/adr/0151: the Instance's API Keys, each shown once, by create, and never again.
7750
7831
  const syntax =
7751
- "ez key list | create <name> [--groups <a,b>] [--expires <days>] | revoke <name>";
7752
- const VALUES = ["--groups", "--expires"];
7832
+ "ez key list | create <name> [--groups <a,b>] [--sites <all | ids>] [--expires <days>] | revoke <name>";
7833
+ const VALUES = ["--groups", "--sites", "--expires"];
7753
7834
  /** @type {Record<string, string>} */
7754
7835
  const given = {};
7755
7836
  const words = [];
@@ -7773,6 +7854,7 @@ async function execute(ws, argv, stdin) {
7773
7854
  k.state,
7774
7855
  `${k.prefix}...`,
7775
7856
  `groups: ${k.groups.length ? k.groups.join(", ") : "none"}`,
7857
+ `sites: ${k.sites === "all" ? "all" : k.sites.length ? k.sites.join(", ") : "none"}`,
7776
7858
  k.state === "revoked" && k.revokedAt
7777
7859
  ? `revoked ${utcMinute(k.revokedAt)}`
7778
7860
  : `expires ${utcMinute(k.expiresAt)}`,
@@ -7793,6 +7875,14 @@ async function execute(ws, argv, stdin) {
7793
7875
  if (sub === "create") {
7794
7876
  const groups = given["--groups"]?.split(",").map((g) => g.trim()) ?? [];
7795
7877
  if (groups.some((g) => !g)) throw new Error("--groups is a comma-separated list of names.");
7878
+ /** @type {"all" | string[] | undefined} */
7879
+ let sites;
7880
+ if (given["--sites"] !== undefined) {
7881
+ sites =
7882
+ given["--sites"] === "all" ? "all" : given["--sites"].split(",").map((id) => id.trim());
7883
+ if (sites !== "all" && sites.some((id) => !isValidSiteId(id)))
7884
+ throw new Error("--sites is all, or Site ids separated by commas.");
7885
+ }
7796
7886
  let expiresInDays;
7797
7887
  if (given["--expires"] !== undefined) {
7798
7888
  expiresInDays = Number(given["--expires"]);
@@ -7806,6 +7896,7 @@ async function execute(ws, argv, stdin) {
7806
7896
  const created = await ws.createApiKey({
7807
7897
  name,
7808
7898
  ...(groups.length ? { groups } : {}),
7899
+ ...(sites === undefined ? {} : { sites }),
7809
7900
  ...(expiresInDays === undefined ? {} : { expiresInDays }),
7810
7901
  });
7811
7902
  const k = created.apiKey;
@@ -7816,6 +7907,11 @@ async function execute(ws, argv, stdin) {
7816
7907
  `This is ${name}'s key; it is shown only now. Give it to the other system as a secret:`,
7817
7908
  ` Authorization: Bearer <key>, against ${created.url}`,
7818
7909
  `It acts as ${k.actor}${k.groups.length ? ` with the groups ${k.groups.join(", ")}` : " with no groups"}, under global/db/access.sql, until ${utcMinute(k.expiresAt)}.`,
7910
+ k.sites === "all"
7911
+ ? "It may call { api: true } server functions on every unrestricted Site."
7912
+ : k.sites.length
7913
+ ? `It may call { api: true } server functions on ${k.sites.join(", ")}.`
7914
+ : "It calls no server functions; --sites says which Sites it may.",
7819
7915
  ].join("\n"),
7820
7916
  created,
7821
7917
  );
package/connections.mjs CHANGED
@@ -9,7 +9,7 @@ export const MANAGED_DOMAIN = "ezship.dev";
9
9
  * The contract's compatibility number (ADR 0072): raised only by a change an older client cannot survive.
10
10
  * @type {typeof import("./connections.d.mts").CONTRACT}
11
11
  */
12
- export const CONTRACT = 1;
12
+ export const CONTRACT = 2;
13
13
  /**
14
14
  * The oldest client contract this release still serves; a Host answers an older one 426.
15
15
  * @type {typeof import("./connections.d.mts").OLDEST_CONTRACT}
Binary file
package/ez.mjs CHANGED
@@ -1019,7 +1019,8 @@ async function dev(creds, args, dir) {
1019
1019
  */
1020
1020
  function needsSite(cmd, args) {
1021
1021
  if (cmd === "site" && args[0] === "access") return true;
1022
- if (cmd === "audit" || cmd === "db" || cmd === "support" || cmd === "email") return false;
1022
+ if (cmd === "audit" || cmd === "db" || cmd === "support" || cmd === "email" || cmd === "key")
1023
+ return false;
1023
1024
  return !["instance", "builders", "builder", "users", "user", "site", "help", "asset"].includes(
1024
1025
  cmd,
1025
1026
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ezship",
3
- "version": "0.1.13",
3
+ "version": "0.1.15",
4
4
  "description": "ez, the ezship command line. The same files as @ezship/cli.",
5
5
  "license": "Apache-2.0",
6
6
  "bin": {
package/types.d.mts CHANGED
@@ -78,7 +78,27 @@ export type Site = {
78
78
  };
79
79
 
80
80
  /** The Site row plus the shared files' version, its app URL and the caller's role (`ez config`, Workspace.remoteStatus). */
81
- export type WorkspaceInfo = Site & { version: Version; appUrl: string | null; role: BuilderRole };
81
+ export type WorkspaceInfo = Site & {
82
+ version: Version;
83
+ appUrl: string | null;
84
+ role: BuilderRole;
85
+ /**
86
+ * The Global Workspace's Version the Site's latest deploy compiled in (docs/adr/0141; 0 when Global was never
87
+ * pushed then), null when the Site has no recorded deploy. Absent from a Host older than the field.
88
+ */
89
+ deployedGlobal?: number | null;
90
+ };
91
+
92
+ /**
93
+ * What a Site's next deploy brings in from the Global Workspace (`ez status`, docs/adr/0141): the Version its
94
+ * live app was built with, the newest pushed one, and the files changed between them that reach an app only at
95
+ * a deploy (`pinnedGlobalPath`). `paths` is null when the live one is no longer retained.
96
+ */
97
+ export type GlobalSinceDeploy = {
98
+ deployed: number;
99
+ current: number;
100
+ paths: { added: string[]; changed: string[]; removed: string[] } | null;
101
+ };
82
102
 
83
103
  /**
84
104
  * What a push did (Workspace.pushAll). A Global push also lists its Live changes (docs/adr/0096), which took
@@ -663,14 +683,15 @@ export type ListenerEvent = {
663
683
  body?: string;
664
684
  };
665
685
  /**
666
- * An API Key as `ez key list` shows it (docs/adr/0119): never the key, only its first characters. `actor` is
667
- * what History records its writes as.
686
+ * An API Key as `ez key list` shows it (docs/adr/0119, docs/adr/0151): never the key, only its first characters.
687
+ * `actor` is what History records its writes as; `sites` is whose `{ api: true }` functions it may call.
668
688
  */
669
689
  export type ApiKey = {
670
690
  name: string;
671
691
  actor: string;
672
692
  prefix: string;
673
693
  groups: string[];
694
+ sites: "all" | string[];
674
695
  createdBy: string;
675
696
  createdAt: number;
676
697
  expiresAt: number;
@@ -678,8 +699,13 @@ export type ApiKey = {
678
699
  revokedAt: number | null;
679
700
  state: "active" | "expired" | "revoked";
680
701
  };
681
- export type ApiKeyInput = { name: string; groups?: string[]; expiresInDays?: number };
682
- /** A new API Key: `key` is shown this once and never stored. `url` is the Site API's door. */
702
+ export type ApiKeyInput = {
703
+ name: string;
704
+ groups?: string[];
705
+ sites?: "all" | string[];
706
+ expiresInDays?: number;
707
+ };
708
+ /** A new API Key: `key` is shown this once and never stored. `url` is the Data API's door. */
683
709
  export type CreatedApiKey = { apiKey: ApiKey; key: string; url: string };
684
710
  /** One global/schedules.json entry (ADRs 0076, 0136): run `global/jobs/<job>.ts` with `input` on a UTC `cron`. */
685
711
  export type ScheduleEntry = {