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 +18 -2
- package/commands.mjs +131 -35
- package/connections.mjs +1 -1
- package/editor-types.json.gz +0 -0
- package/ez.mjs +2 -1
- package/package.json +1 -1
- package/types.d.mts +31 -5
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
|
|
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
|
|
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
|
|
231
|
-
* `Authorization: Bearer ezk_
|
|
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
|
|
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").
|
|
244
|
-
export const
|
|
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
|
|
3924
|
-
listApiKeys: { method: "GET", path: `${
|
|
3925
|
-
createApiKey: { method: "POST", path: `${
|
|
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: `${
|
|
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
|
|
4781
|
-
const API_TOPIC = `The
|
|
4782
|
-
and write this
|
|
4783
|
-
An Admin creates an API Key in a terminal: \`ez key create warehouse
|
|
4784
|
-
prints the key (${API_KEY_PREFIX}...) once; give it to the
|
|
4785
|
-
or in Site code. \`ez key list\` shows every key
|
|
4786
|
-
|
|
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
|
|
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.
|
|
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]
|
|
4800
|
-
|
|
4801
|
-
|
|
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};
|
|
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
|
|
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
|
|
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
|
|
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"
|
|
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:
|
|
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 =
|
|
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}
|
package/editor-types.json.gz
CHANGED
|
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"
|
|
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
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 & {
|
|
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.
|
|
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 = {
|
|
682
|
-
|
|
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 = {
|