ezship 0.1.16 → 0.1.17
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/README.md +60 -56
- package/access.d.mts +4 -4
- package/access.mjs +13 -13
- package/account.mjs +9 -8
- package/bindings.mjs +9 -27
- package/commands.d.mts +64 -67
- package/commands.mjs +1264 -529
- package/connections.d.mts +2 -3
- package/connections.mjs +10 -22
- package/cron.d.mts +1 -1
- package/cron.mjs +1 -1
- package/documents.d.mts +1 -1
- package/documents.mjs +1 -1
- package/editor-types.json.gz +0 -0
- package/editor.mjs +22 -56
- package/ez.mjs +48 -133
- package/package.json +7 -1
- package/paths.d.mts +22 -0
- package/paths.mjs +95 -0
- package/schema.d.mts +45 -49
- package/schema.mjs +364 -219
- package/session.d.mts +2 -3
- package/session.mjs +3 -5
- package/shape.d.mts +2 -2
- package/shape.mjs +1 -1
- package/signup.mjs +2 -2
- package/types.d.mts +73 -73
- package/update-check.mjs +1 -1
- package/workflow.d.mts +8 -2
- package/workflow.mjs +88 -21
package/ez.mjs
CHANGED
|
@@ -1,16 +1,9 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// Instance-connected terminal adapter (ADR
|
|
2
|
+
// Instance-connected terminal adapter (ADR 0202). The shared command contract lives in commands.mjs.
|
|
3
3
|
import { localFetch } from "./local-fetch.mjs";
|
|
4
4
|
import { checkForUpdate } from "./update-check.mjs";
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
7
|
-
adoptBinding,
|
|
8
|
-
bindingFile,
|
|
9
|
-
instanceFolderOf,
|
|
10
|
-
moveWorkingCopy,
|
|
11
|
-
readBinding,
|
|
12
|
-
writeBinding,
|
|
13
|
-
} from "./bindings.mjs";
|
|
5
|
+
import { ensureEditor } from "./editor.mjs";
|
|
6
|
+
import { instanceFolderOf, moveWorkingCopy, readBinding, writeBinding } from "./bindings.mjs";
|
|
14
7
|
import { passwordLogin, runAccountCommand, ACCOUNT_COMMANDS } from "./account.mjs";
|
|
15
8
|
import {
|
|
16
9
|
connectionKey,
|
|
@@ -19,7 +12,6 @@ import {
|
|
|
19
12
|
connectionRequest,
|
|
20
13
|
CONTRACT,
|
|
21
14
|
CONTRACT_HEADER,
|
|
22
|
-
contractNote,
|
|
23
15
|
readConnections,
|
|
24
16
|
saveConnection,
|
|
25
17
|
findConnection,
|
|
@@ -65,15 +57,12 @@ const CRED_FILE = join(CRED_DIR, "connections.json");
|
|
|
65
57
|
const SKIP_DIRS = new Set(["node_modules", ".git", ".ez"]);
|
|
66
58
|
const VALUE_FLAGS = [
|
|
67
59
|
"--account",
|
|
68
|
-
"--from-api",
|
|
69
|
-
"--from-instance",
|
|
70
60
|
"--global-dir",
|
|
71
61
|
"--username",
|
|
72
62
|
"--name",
|
|
73
63
|
"--site",
|
|
74
64
|
"--instance",
|
|
75
65
|
"--dir",
|
|
76
|
-
"--api",
|
|
77
66
|
"--email",
|
|
78
67
|
"--kind",
|
|
79
68
|
"--limit",
|
|
@@ -89,13 +78,9 @@ async function readCredFile() {
|
|
|
89
78
|
* @param {string[]} args @param {string | undefined} [dir] @param {string} [command]
|
|
90
79
|
*/
|
|
91
80
|
async function loadCreds(args = [], dir, command = "") {
|
|
92
|
-
if (process.env.EZ_API || flag(args, "--api"))
|
|
93
|
-
throw new Error(
|
|
94
|
-
"Host API connections are retired. Use ez login <Instance URL> and --instance instead.",
|
|
95
|
-
);
|
|
96
81
|
const saved = await readCredFile();
|
|
97
82
|
const explicit = extractTarget([command, ...args]);
|
|
98
|
-
const bound = dir
|
|
83
|
+
const bound = dir ? await boundTarget(dir) : null;
|
|
99
84
|
const positionalTarget =
|
|
100
85
|
command === "clone"
|
|
101
86
|
? positionals(args)[0]
|
|
@@ -103,26 +88,26 @@ async function loadCreds(args = [], dir, command = "") {
|
|
|
103
88
|
? parseTarget(positionals(args)[0] || "")?.instance
|
|
104
89
|
: undefined;
|
|
105
90
|
const target = explicit.instance || process.env.EZ_INSTANCE || positionalTarget;
|
|
106
|
-
if (bound && !bound.uid && !target)
|
|
107
|
-
throw new Error(
|
|
108
|
-
"This is a legacy Working Copy. Connect to its Instance, then use ez adopt with an explicit source and target.",
|
|
109
|
-
);
|
|
110
91
|
let connection;
|
|
111
92
|
try {
|
|
112
93
|
connection = findConnection(
|
|
113
94
|
saved,
|
|
114
95
|
target ||
|
|
115
|
-
(bound
|
|
116
|
-
?
|
|
117
|
-
?
|
|
118
|
-
:
|
|
96
|
+
(bound
|
|
97
|
+
? explicit.account
|
|
98
|
+
? instanceKey({ app: bound.app ?? "", uid: bound.uid ?? "" })
|
|
99
|
+
: connectionKey({
|
|
100
|
+
app: bound.app ?? "",
|
|
101
|
+
uid: bound.uid ?? "",
|
|
102
|
+
builder: bound.builder ?? "",
|
|
103
|
+
})
|
|
119
104
|
: undefined),
|
|
120
105
|
explicit.account,
|
|
121
106
|
);
|
|
122
107
|
} catch (e) {
|
|
123
108
|
// A folder bound to a forgotten connection: name where it belongs and the exact
|
|
124
109
|
// login that restores it, instead of the binding's internal key.
|
|
125
|
-
if (!target && bound
|
|
110
|
+
if (!target && bound)
|
|
126
111
|
throw new Error(
|
|
127
112
|
`This Working Copy belongs to ${bound.instance} (${bound.app}). That connection is not saved here. Run: ez login ${bound.app}`,
|
|
128
113
|
{ cause: e },
|
|
@@ -159,14 +144,10 @@ async function saveLogin(descriptor, token) {
|
|
|
159
144
|
|
|
160
145
|
/** @param {Connection} connection @param {Binding} bound */
|
|
161
146
|
function assertFolder(connection, bound) {
|
|
162
|
-
if (!bound.uid)
|
|
163
|
-
throw new Error(
|
|
164
|
-
"This is a legacy Working Copy. Use ez adopt with its explicit source and target before changing files.",
|
|
165
|
-
);
|
|
166
147
|
if (
|
|
167
148
|
bound.uid !== connection.uid ||
|
|
168
149
|
bound.app !== connection.app ||
|
|
169
|
-
|
|
150
|
+
bound.builder !== connection.builder
|
|
170
151
|
)
|
|
171
152
|
throw new Error(
|
|
172
153
|
`This Working Copy belongs to ${bound.instance} (${bound.email || bound.app}). Use --dir for the target Instance's own folder.`,
|
|
@@ -244,9 +225,9 @@ async function request(creds, method, path, body, { raw = false } = {}) {
|
|
|
244
225
|
try {
|
|
245
226
|
msg = JSON.parse(text).error ?? text;
|
|
246
227
|
} catch {}
|
|
247
|
-
// The Host's request id (ADR
|
|
228
|
+
// The Host's request id (ADR 0243) is what an operator finds in the Host's log.
|
|
248
229
|
const id = res.headers.get("x-request-id");
|
|
249
|
-
throw new Error(`${res.status} ${msg}${id ? ` (request ${id})` : ""}
|
|
230
|
+
throw new Error(`${res.status} ${msg}${id ? ` (request ${id})` : ""}`);
|
|
250
231
|
}
|
|
251
232
|
if (raw) return text;
|
|
252
233
|
try {
|
|
@@ -317,7 +298,7 @@ const targetLine = (t, current) =>
|
|
|
317
298
|
`${current === t.id ? "*" : " "} ${t.instance}/${t.id} (${t.name}, ${t.role})`;
|
|
318
299
|
|
|
319
300
|
/**
|
|
320
|
-
* What a folder already is: a Working Copy (its binding, ADR
|
|
301
|
+
* What a folder already is: a Working Copy (its binding, ADR 0205) or an Instance folder (<dir>/.ez/instance.json).
|
|
321
302
|
* @param {string} dir @returns {Promise<Binding | null>}
|
|
322
303
|
*/
|
|
323
304
|
async function boundTarget(dir) {
|
|
@@ -376,9 +357,9 @@ async function markInstanceFolder(dir, instance, connection) {
|
|
|
376
357
|
|
|
377
358
|
/**
|
|
378
359
|
* `ez clone [<instance>]` / `ez pull --all`: every Site the Builder may open, each pulled into
|
|
379
|
-
* <dir>/sites/<folder>/, and the Global Workspace into <dir>/global/ (ADR
|
|
380
|
-
* are skipped and reported. A
|
|
381
|
-
*
|
|
360
|
+
* <dir>/sites/<folder>/, and the Global Workspace into <dir>/global/ (ADR 0205). Folders with unpushed changes
|
|
361
|
+
* are skipped and reported. A folder whose Site was renamed moves to the new name; the bindings live in
|
|
362
|
+
* <dir>/.ez/ (ADR 0205).
|
|
382
363
|
* @param {Connection} creds @param {string[]} args @param {string} dir
|
|
383
364
|
*/
|
|
384
365
|
async function cloneInstance(creds, args, dir) {
|
|
@@ -394,19 +375,12 @@ async function cloneInstance(creds, args, dir) {
|
|
|
394
375
|
const mine = instances.find((i) => i.id === instance);
|
|
395
376
|
if (!mine) throw new Error(`You are not a builder of "${instance}". Run \`ez sites\`.`);
|
|
396
377
|
const sitesDir = join(dir, SITES_FOLDER);
|
|
397
|
-
const occupant = await boundTarget(sitesDir);
|
|
398
|
-
if (occupant?.site)
|
|
399
|
-
throw new Error(
|
|
400
|
-
`${sitesDir} is the working copy of ${occupant.instance}/${occupant.site}, but Site folders now live inside sites/. Rename that folder, then run this again.`,
|
|
401
|
-
);
|
|
402
378
|
await markInstanceFolder(dir, instance, creds);
|
|
403
|
-
// Bindings live in this folder's .ez/, keyed by folder name (ADR
|
|
404
|
-
//
|
|
379
|
+
// Bindings live in this folder's .ez/, keyed by folder name (ADR 0205): the ones whose folder is gone are
|
|
380
|
+
// dropped, so a new folder of that name never inherits another Site's baseline.
|
|
405
381
|
const siteFolders = (await readdir(sitesDir, { withFileTypes: true }).catch(() => []))
|
|
406
382
|
.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
|
|
407
383
|
.map((entry) => entry.name);
|
|
408
|
-
for (const name of siteFolders) await adoptBinding(join(sitesDir, name));
|
|
409
|
-
await adoptBinding(join(dir, GLOBAL_ID));
|
|
410
384
|
const bindings = join(dir, ".ez", SITES_FOLDER);
|
|
411
385
|
for (const file of await readdir(bindings).catch(() => []))
|
|
412
386
|
if (file.endsWith(".json") && !siteFolders.includes(file.slice(0, -".json".length)))
|
|
@@ -418,7 +392,7 @@ async function cloneInstance(creds, args, dir) {
|
|
|
418
392
|
const b = await readBinding(folder);
|
|
419
393
|
return b?.uid && b?.site ? `${b.uid}\0${b.site}` : null;
|
|
420
394
|
};
|
|
421
|
-
// Existing folders, keyed by what they are bound to (docs/adr/
|
|
395
|
+
// Existing folders, keyed by what they are bound to (docs/adr/0205).
|
|
422
396
|
/** @type {Map<string,string>} */
|
|
423
397
|
const boundDirs = new Map();
|
|
424
398
|
const unbound = [];
|
|
@@ -430,15 +404,6 @@ async function cloneInstance(creds, args, dir) {
|
|
|
430
404
|
if (key) boundDirs.set(key, entry.name);
|
|
431
405
|
else if (entry.isDirectory()) unbound.push(entry.name);
|
|
432
406
|
}
|
|
433
|
-
// Site folders from before sites/ sit beside global/; each one moves in.
|
|
434
|
-
/** @type {Map<string,string>} */
|
|
435
|
-
const legacyDirs = new Map();
|
|
436
|
-
for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
|
|
437
|
-
if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
|
|
438
|
-
if (entry.name === GLOBAL_ID || entry.name === SITES_FOLDER) continue;
|
|
439
|
-
const key = await bindingOf(join(dir, entry.name));
|
|
440
|
-
if (key && !boundDirs.has(key)) legacyDirs.set(key, entry.name);
|
|
441
|
-
}
|
|
442
407
|
/** @param {string} base */
|
|
443
408
|
const claim = (base) => {
|
|
444
409
|
let candidate = base;
|
|
@@ -451,18 +416,13 @@ async function cloneInstance(creds, args, dir) {
|
|
|
451
416
|
folder === slug ||
|
|
452
417
|
(folder.startsWith(`${slug}-`) && /^\d+$/.test(folder.slice(slug.length + 1)));
|
|
453
418
|
// A folder is named for its Site, not its ID; collisions take -2, -3, and so on. Folders follow Site
|
|
454
|
-
// renames (ADR
|
|
419
|
+
// renames (ADR 0205): a bound folder whose Site was renamed moves to the new name.
|
|
455
420
|
/** @param {InstanceSummary["sites"][number]} site @returns {{name: string, from?: string}} */
|
|
456
421
|
const folderFor = (site) => {
|
|
457
422
|
const key = `${creds.uid}\0${site.id}`;
|
|
458
423
|
const slug = siteFolderName(site.name ?? site.id);
|
|
459
424
|
const known = boundDirs.get(key);
|
|
460
|
-
if (known)
|
|
461
|
-
return named(known, slug)
|
|
462
|
-
? { name: known }
|
|
463
|
-
: { name: claim(slug), from: `${SITES_FOLDER}/${known}` };
|
|
464
|
-
const legacy = legacyDirs.get(key);
|
|
465
|
-
if (legacy) return { name: claim(named(legacy, slug) ? legacy : slug), from: legacy };
|
|
425
|
+
if (known) return named(known, slug) ? { name: known } : { name: claim(slug), from: known };
|
|
466
426
|
return { name: claim(slug) };
|
|
467
427
|
};
|
|
468
428
|
const lines = [];
|
|
@@ -471,8 +431,8 @@ async function cloneInstance(creds, args, dir) {
|
|
|
471
431
|
const folder = `${SITES_FOLDER}/${name}`;
|
|
472
432
|
const sub = join(sitesDir, name);
|
|
473
433
|
if (from) {
|
|
474
|
-
await moveWorkingCopy(join(
|
|
475
|
-
lines.push(`${folder}/ moved from ${from}/`);
|
|
434
|
+
await moveWorkingCopy(join(sitesDir, from), sub);
|
|
435
|
+
lines.push(`${folder}/ moved from ${SITES_FOLDER}/${from}/`);
|
|
476
436
|
}
|
|
477
437
|
const ws = diskWorkspace(creds, instance, s.id, sub);
|
|
478
438
|
const [files, pulled] = await Promise.all([ws.files(), ws.pulled()]);
|
|
@@ -516,7 +476,7 @@ async function cloneInstance(creds, args, dir) {
|
|
|
516
476
|
* The Instance and, when `needSite`, the Site to act on: --site / EZ_SITE / `ez use` (an "<instance>/<site>"
|
|
517
477
|
* or a bare "<site>"), --instance for Instance-only commands, else implied when the Builder is in exactly one.
|
|
518
478
|
* Fails with the list when it is ambiguous. `boundSite` keeps a Site folder's Site for an Instance command
|
|
519
|
-
* that only mentions it (`ez support open`, docs/adr/
|
|
479
|
+
* that only mentions it (`ez support open`, docs/adr/0208).
|
|
520
480
|
* @param {Connection} creds @param {string[]} args @param {{needSite: boolean, boundSite?: boolean, dir?: string}} options
|
|
521
481
|
*/
|
|
522
482
|
async function resolveTarget(creds, args, { needSite, boundSite, dir }) {
|
|
@@ -546,7 +506,7 @@ async function resolveTarget(creds, args, { needSite, boundSite, dir }) {
|
|
|
546
506
|
}
|
|
547
507
|
|
|
548
508
|
/**
|
|
549
|
-
* A password or a secret, never an argument: piped (scripts, CI), the whole of stdin, like `
|
|
509
|
+
* A password or a secret, never an argument: piped (scripts, CI), the whole of stdin, like `host
|
|
550
510
|
* create-developer`; in a terminal, a prompt that does not echo.
|
|
551
511
|
* @param {string} [label] @returns {Promise<string>}
|
|
552
512
|
*/
|
|
@@ -600,8 +560,6 @@ async function ask(question) {
|
|
|
600
560
|
* @param {string[]} args
|
|
601
561
|
*/
|
|
602
562
|
async function login(args) {
|
|
603
|
-
if (flag(args, "--api"))
|
|
604
|
-
throw new Error("Use ez login <Instance URL>; --api is reserved for operator tooling.");
|
|
605
563
|
const descriptor = await discoverInstance(
|
|
606
564
|
positionals(args)[0] || process.env.EZ_INSTANCE || "",
|
|
607
565
|
localFetch,
|
|
@@ -625,7 +583,11 @@ async function login(args) {
|
|
|
625
583
|
throw new Error(
|
|
626
584
|
"Usage: ez login <instance or URL> [--email you@example.com] [--browser]\nAn email address is required.",
|
|
627
585
|
);
|
|
628
|
-
const headers = {
|
|
586
|
+
const headers = {
|
|
587
|
+
"content-type": "application/json",
|
|
588
|
+
origin: api,
|
|
589
|
+
[CONTRACT_HEADER]: String(CONTRACT),
|
|
590
|
+
};
|
|
629
591
|
/** @param {string} path @param {unknown} body @param {Record<string,string>} [extra] */
|
|
630
592
|
const post = (path, body, extra = {}) =>
|
|
631
593
|
localFetch(api + path, {
|
|
@@ -711,50 +673,6 @@ async function logout(args) {
|
|
|
711
673
|
console.log(`Disconnected ${connection.instance} (${connection.email}).`);
|
|
712
674
|
}
|
|
713
675
|
|
|
714
|
-
/** @param {Connection} connection @param {string[]} args @param {string} dir */
|
|
715
|
-
async function adoptFolder(connection, args, dir) {
|
|
716
|
-
const bound = await boundTarget(dir);
|
|
717
|
-
if (!bound || bound.uid) throw new Error("This folder is not a legacy Working Copy.");
|
|
718
|
-
if (!flag(args, "--instance"))
|
|
719
|
-
throw new Error("Adoption requires an explicit --instance target.");
|
|
720
|
-
if (
|
|
721
|
-
flag(args, "--from-instance") !== bound.instance ||
|
|
722
|
-
(bound.api && flag(args, "--from-api") !== bound.api)
|
|
723
|
-
)
|
|
724
|
-
throw new Error(
|
|
725
|
-
`Verify the source with --from-instance ${bound.instance}` +
|
|
726
|
-
(bound.api ? ` --from-api ${bound.api}` : "") +
|
|
727
|
-
". No files have changed.",
|
|
728
|
-
);
|
|
729
|
-
const target = bound.site || null;
|
|
730
|
-
if (target)
|
|
731
|
-
await request(connection, "GET", `/api/i/${connection.instance}/s/${target}/workspace`);
|
|
732
|
-
else await request(connection, "GET", `/api/i/${connection.instance}`);
|
|
733
|
-
const file = target
|
|
734
|
-
? /** @type {string} */ (await bindingFile(dir))
|
|
735
|
-
: join(dir, ".ez", "instance.json");
|
|
736
|
-
await writeFile(file + ".legacy", await readFile(file), { flag: "wx" });
|
|
737
|
-
await writeFile(
|
|
738
|
-
file,
|
|
739
|
-
JSON.stringify(
|
|
740
|
-
{
|
|
741
|
-
...bound,
|
|
742
|
-
instance: connection.instance,
|
|
743
|
-
uid: connection.uid,
|
|
744
|
-
app: connection.app,
|
|
745
|
-
api: connection.api,
|
|
746
|
-
builder: connection.builder,
|
|
747
|
-
email: connection.email,
|
|
748
|
-
},
|
|
749
|
-
null,
|
|
750
|
-
2,
|
|
751
|
-
) + "\n",
|
|
752
|
-
);
|
|
753
|
-
console.log(
|
|
754
|
-
`Bound this folder to ${connection.instance} (${connection.email}); unpushed files retained.`,
|
|
755
|
-
);
|
|
756
|
-
}
|
|
757
|
-
|
|
758
676
|
// ---- the working copy on disk + the Instance's and Site's HTTP API, as the contract's Workspace -----------
|
|
759
677
|
|
|
760
678
|
/** @param {string} dir @param {string} [base] @returns {Promise<string[]>} */
|
|
@@ -810,7 +728,7 @@ function diskWorkspace(creds, instance, site, dir, globalDir) {
|
|
|
810
728
|
meta.site !== GLOBAL_ID ||
|
|
811
729
|
meta.uid !== creds.uid ||
|
|
812
730
|
meta.app !== creds.app ||
|
|
813
|
-
|
|
731
|
+
meta.builder !== creds.builder)
|
|
814
732
|
)
|
|
815
733
|
throw new Error("Global Working Copy belongs to a different target.");
|
|
816
734
|
return global;
|
|
@@ -885,7 +803,6 @@ function diskWorkspace(creds, instance, site, dir, globalDir) {
|
|
|
885
803
|
async setPulled(p) {
|
|
886
804
|
await writeBinding(dir, {
|
|
887
805
|
...p,
|
|
888
|
-
api: creds.api,
|
|
889
806
|
instance,
|
|
890
807
|
site,
|
|
891
808
|
uid: creds.uid,
|
|
@@ -902,7 +819,7 @@ function diskWorkspace(creds, instance, site, dir, globalDir) {
|
|
|
902
819
|
: join(instanceFolderOf(dir), GLOBAL_ID),
|
|
903
820
|
);
|
|
904
821
|
},
|
|
905
|
-
// the default Preview name: this folder's (a worktree per feature is a Preview per feature; docs/adr/
|
|
822
|
+
// the default Preview name: this folder's (a worktree per feature is a Preview per feature; docs/adr/0212)
|
|
906
823
|
async globalFiles() {
|
|
907
824
|
if (site === GLOBAL_ID) return undefined;
|
|
908
825
|
const folder = globalDir ? resolve(globalDir) : join(instanceFolderOf(dir), GLOBAL_ID);
|
|
@@ -916,7 +833,7 @@ function diskWorkspace(creds, instance, site, dir, globalDir) {
|
|
|
916
833
|
meta.site !== GLOBAL_ID ||
|
|
917
834
|
meta.uid !== creds.uid ||
|
|
918
835
|
meta.app !== creds.app ||
|
|
919
|
-
|
|
836
|
+
meta.builder !== creds.builder
|
|
920
837
|
)
|
|
921
838
|
throw new Error("Global Working Copy belongs to a different target.");
|
|
922
839
|
return diskWorkspace(creds, instance, GLOBAL_ID, folder).files();
|
|
@@ -924,7 +841,6 @@ function diskWorkspace(creds, instance, site, dir, globalDir) {
|
|
|
924
841
|
async previewName() {
|
|
925
842
|
return previewNameFrom(basename(resolve(dir)));
|
|
926
843
|
},
|
|
927
|
-
editorExports,
|
|
928
844
|
};
|
|
929
845
|
}
|
|
930
846
|
|
|
@@ -935,12 +851,12 @@ async function readStdin() {
|
|
|
935
851
|
return Buffer.concat(chunks).toString("utf8");
|
|
936
852
|
}
|
|
937
853
|
|
|
938
|
-
// ---- ez dev: a watcher over `ez preview` (docs/adr/
|
|
854
|
+
// ---- ez dev: a watcher over `ez preview` (docs/adr/0212) --------------------------------------------------
|
|
939
855
|
|
|
940
856
|
/**
|
|
941
857
|
* `ez dev [--name <preview>]`: `ez preview` once, then again after every change in this folder (debounced; a
|
|
942
858
|
* change during an upload queues one more). Nothing runs here but the watcher: the build and the app are on
|
|
943
|
-
* the Host. The Preview page reloads itself after successful builds (docs/adr/
|
|
859
|
+
* the Host. The Preview page reloads itself after successful builds (docs/adr/0212).
|
|
944
860
|
* @param {Connection} creds @param {string[]} args @param {string} dir
|
|
945
861
|
*/
|
|
946
862
|
async function dev(creds, args, dir) {
|
|
@@ -1082,14 +998,13 @@ async function main() {
|
|
|
1082
998
|
// The connection lines open the top-level help only; a topic (`ez help rules`) is just the topic.
|
|
1083
999
|
if (!args.length)
|
|
1084
1000
|
console.log(
|
|
1085
|
-
"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
|
|
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].",
|
|
1086
1002
|
);
|
|
1087
1003
|
// Help does not read any Workspace methods.
|
|
1088
1004
|
return console.log(await runCommand(/** @type {Workspace} */ ({}), ["help", ...args]));
|
|
1089
1005
|
}
|
|
1090
1006
|
const dir = resolve(flag(args, "--dir") || process.env.EZ_DIR || ".");
|
|
1091
1007
|
const creds = await loadCreds(args, dir, cmd);
|
|
1092
|
-
if (cmd === "adopt") return adoptFolder(creds, args, dir);
|
|
1093
1008
|
if (cmd === "account") {
|
|
1094
1009
|
if (!creds.api) throw new Error("Connect to an Instance with ez login first.");
|
|
1095
1010
|
const url = creds.api + (args.includes("--password") ? "/password-setup" : "/account");
|
|
@@ -1130,7 +1045,7 @@ async function main() {
|
|
|
1130
1045
|
}
|
|
1131
1046
|
case "instance":
|
|
1132
1047
|
// Creating and archiving Instances is developer-only and lives in scripts/instance.mjs, not here.
|
|
1133
|
-
if (["create", "archive"
|
|
1048
|
+
if (["create", "archive"].includes(positional[0]))
|
|
1134
1049
|
throw new Error(
|
|
1135
1050
|
"Creating and archiving instances is developer-only: bun scripts/instance.mjs create|archive ...",
|
|
1136
1051
|
);
|
|
@@ -1188,7 +1103,7 @@ async function main() {
|
|
|
1188
1103
|
|
|
1189
1104
|
if (!COMMAND_NAMES.includes(cmd)) {
|
|
1190
1105
|
console.log(
|
|
1191
|
-
"Usage: ez login|logout|logins|switch|
|
|
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",
|
|
1192
1107
|
);
|
|
1193
1108
|
process.exitCode = 1;
|
|
1194
1109
|
return;
|
|
@@ -1230,21 +1145,21 @@ async function main() {
|
|
|
1230
1145
|
(args[0] === "set" || args[0] === "preview") &&
|
|
1231
1146
|
(args.includes("--header") || args.includes("--query"))
|
|
1232
1147
|
) {
|
|
1233
|
-
// docs/adr/
|
|
1148
|
+
// docs/adr/0231: a credential's value is typed at a hidden prompt or piped, never an argument.
|
|
1234
1149
|
stdin = await askPassword("credential value");
|
|
1235
1150
|
} else if (
|
|
1236
1151
|
cmd === "integration" &&
|
|
1237
1152
|
(args[0] === "set" || args[0] === "preview") &&
|
|
1238
1153
|
args.includes("--basic")
|
|
1239
1154
|
) {
|
|
1240
|
-
// docs/adr/
|
|
1155
|
+
// docs/adr/0231: a basic credential's password, the same way.
|
|
1241
1156
|
stdin = await askPassword("password");
|
|
1242
1157
|
} else if (
|
|
1243
1158
|
cmd === "integration" &&
|
|
1244
1159
|
(args[0] === "set" || args[0] === "preview") &&
|
|
1245
1160
|
(args.includes("--oauth") || args.includes("--preset"))
|
|
1246
1161
|
) {
|
|
1247
|
-
// docs/adr/
|
|
1162
|
+
// docs/adr/0252: the client secret, then a password grant's password: two lines piped, or two prompts.
|
|
1248
1163
|
const grant = flag(args, "--oauth");
|
|
1249
1164
|
stdin = process.stdin.isTTY
|
|
1250
1165
|
? [
|
|
@@ -1253,10 +1168,10 @@ async function main() {
|
|
|
1253
1168
|
].join("\n")
|
|
1254
1169
|
: ((await readStdin()) ?? "");
|
|
1255
1170
|
} else if (cmd === "integration" && args[0] === "value" && args.includes("--secret")) {
|
|
1256
|
-
// docs/adr/
|
|
1171
|
+
// docs/adr/0231: a secret value, the same way as a credential's.
|
|
1257
1172
|
stdin = await askPassword("secret value");
|
|
1258
1173
|
} else if (cmd === "listener" && args[0] === "secret" && !args.includes("--remove")) {
|
|
1259
|
-
// docs/adr/
|
|
1174
|
+
// docs/adr/0231: a Listener's secret, the same way.
|
|
1260
1175
|
stdin = await askPassword("listener secret");
|
|
1261
1176
|
} else if (cmd === "support" && args[0] === "open" && !args.includes("--body")) {
|
|
1262
1177
|
// `ez support open <subject>` takes its body from a pipe when --body is not given.
|
|
@@ -1267,7 +1182,7 @@ async function main() {
|
|
|
1267
1182
|
}
|
|
1268
1183
|
|
|
1269
1184
|
/**
|
|
1270
|
-
* Whether a newer `ez` is on npm (docs/adr/
|
|
1185
|
+
* Whether a newer `ez` is on npm (docs/adr/0206), asked alongside the command and told after it, on standard
|
|
1271
1186
|
* error. `ez dev` never ends, so it is not asked. Never fails or fails a command.
|
|
1272
1187
|
*/
|
|
1273
1188
|
async function updateCheck() {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ezship",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.17",
|
|
4
4
|
"description": "ez, the ezship command line. The same files as @ezship/cli.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"bin": {
|
|
@@ -14,6 +14,8 @@
|
|
|
14
14
|
"local-fetch.mjs",
|
|
15
15
|
"commands.mjs",
|
|
16
16
|
"commands.d.mts",
|
|
17
|
+
"paths.mjs",
|
|
18
|
+
"paths.d.mts",
|
|
17
19
|
"schema.mjs",
|
|
18
20
|
"schema.d.mts",
|
|
19
21
|
"access.mjs",
|
|
@@ -54,6 +56,10 @@
|
|
|
54
56
|
"types": "./commands.d.mts",
|
|
55
57
|
"default": "./commands.mjs"
|
|
56
58
|
},
|
|
59
|
+
"./paths": {
|
|
60
|
+
"types": "./paths.d.mts",
|
|
61
|
+
"default": "./paths.mjs"
|
|
62
|
+
},
|
|
57
63
|
"./schema": {
|
|
58
64
|
"types": "./schema.d.mts",
|
|
59
65
|
"default": "./schema.mjs"
|
package/paths.d.mts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Hand-written declarations for cli/paths.mjs: what a deployed page and the app host say to each other
|
|
2
|
+
// (docs/adr/0216). The Framework's only runtime import of the contract.
|
|
3
|
+
|
|
4
|
+
export const FUNCTION_BASE_PATH: "/_ez/functions";
|
|
5
|
+
export const DOCUMENT_BASE_PATH: "/_ez/documents";
|
|
6
|
+
/** Live Table versions for pages (docs/adr/0220): the push stream, the one-shot map, and the write header. */
|
|
7
|
+
export const LIVE_STREAM_PATH: "/_ez/db/stream";
|
|
8
|
+
export const LIVE_VERSIONS_PATH: "/_ez/db/versions";
|
|
9
|
+
/** The declared Tables' access rules for `useCan` (docs/adr/0225). */
|
|
10
|
+
export const ACCESS_RULES_PATH: "/_ez/access";
|
|
11
|
+
/** The active scope's values for the Framework's switcher (docs/adr/0225). */
|
|
12
|
+
export const SCOPE_PATH: "/_ez/scope";
|
|
13
|
+
export const VERSIONS_HEADER: "ez-versions";
|
|
14
|
+
/** Session State (docs/adr/0214): the page's path and the viewer's own counter in the live version map. */
|
|
15
|
+
export const SESSION_PATH: "/_ez/session";
|
|
16
|
+
export const SESSION_VERSION_KEY: "~session";
|
|
17
|
+
export const ASSET_TYPES: Readonly<Record<string, string>>;
|
|
18
|
+
export const ASSET_PATH: "/_ez/files";
|
|
19
|
+
/** App Attachments (docs/adr/0221): the type table and the app-host path. */
|
|
20
|
+
export const ATTACHMENT_TYPES: Readonly<Record<string, string>>;
|
|
21
|
+
export const ATTACHMENT_PATH: "/_ez/attachments";
|
|
22
|
+
export function attachmentContentType(filename: string): string | null;
|
package/paths.mjs
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
// What a deployed page and the app host say to each other (docs/adr/0216): the paths under a Site's prefix,
|
|
2
|
+
// the write header and the file types a page may upload. The Framework imports this module and nothing else
|
|
3
|
+
// of the contract at runtime, so it stays small and imports nothing: whatever is added here is downloaded by
|
|
4
|
+
// every page of every Site. `commands.mjs` and `session.mjs` re-export all of it; import it from there
|
|
5
|
+
// everywhere but the Framework.
|
|
6
|
+
|
|
7
|
+
/** @type {typeof import("./paths.d.mts").FUNCTION_BASE_PATH} */
|
|
8
|
+
export const FUNCTION_BASE_PATH = "/_ez/functions";
|
|
9
|
+
/** @type {typeof import("./paths.d.mts").DOCUMENT_BASE_PATH} */
|
|
10
|
+
export const DOCUMENT_BASE_PATH = "/_ez/documents";
|
|
11
|
+
/**
|
|
12
|
+
* A page's live Table versions (docs/adr/0220): `GET <prefix>/_ez/db/stream` answers `text/event-stream`, each
|
|
13
|
+
* `versions` event the complete map the viewer may read; `GET <prefix>/_ez/db/versions` is the same map once.
|
|
14
|
+
* @type {typeof import("./paths.d.mts").LIVE_STREAM_PATH}
|
|
15
|
+
*/
|
|
16
|
+
export const LIVE_STREAM_PATH = "/_ez/db/stream";
|
|
17
|
+
/** @type {typeof import("./paths.d.mts").LIVE_VERSIONS_PATH} */
|
|
18
|
+
export const LIVE_VERSIONS_PATH = "/_ez/db/versions";
|
|
19
|
+
/**
|
|
20
|
+
* The rules of the Tables this artifact declares (docs/adr/0225): `GET <prefix>/_ez/access` answers
|
|
21
|
+
* `{ rules: { [table]: { read, write } }, workflows: { [table]: WorkflowMeta } }`, what `useCan` evaluates
|
|
22
|
+
* and `useWorkflow` shows (docs/adr/0227). The Host's answer to a write is the authority; these only let a
|
|
23
|
+
* page hide what it would refuse.
|
|
24
|
+
* @type {typeof import("./paths.d.mts").ACCESS_RULES_PATH}
|
|
25
|
+
*/
|
|
26
|
+
export const ACCESS_RULES_PATH = "/_ez/access";
|
|
27
|
+
/**
|
|
28
|
+
* The active scope for the Framework's switcher (docs/adr/0225): `GET <prefix>/_ez/scope` answers
|
|
29
|
+
* `{ scope: { column, key, values: [{ value, label }], active } | null }`.
|
|
30
|
+
* @type {typeof import("./paths.d.mts").SCOPE_PATH}
|
|
31
|
+
*/
|
|
32
|
+
export const SCOPE_PATH = "/_ez/scope";
|
|
33
|
+
/**
|
|
34
|
+
* The response header on a page's writes and function calls: the viewer's version map read after the commit,
|
|
35
|
+
* as JSON, so the page can wait until its live queries show the write.
|
|
36
|
+
* @type {typeof import("./paths.d.mts").VERSIONS_HEADER}
|
|
37
|
+
*/
|
|
38
|
+
export const VERSIONS_HEADER = "ez-versions";
|
|
39
|
+
|
|
40
|
+
/** Where a page reads (GET) and writes (PUT `/<key>`) its viewer's Session State, under the Site's prefix. */
|
|
41
|
+
export const SESSION_PATH = "/_ez/session";
|
|
42
|
+
/** The viewer's own counter in the live version map (docs/adr/0220); no Table can have this name. */
|
|
43
|
+
export const SESSION_VERSION_KEY = "~session";
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Allowed asset types by extension. Limits are data: loosened by platform release, never per Instance.
|
|
47
|
+
* @type {typeof import("./paths.d.mts").ASSET_TYPES}
|
|
48
|
+
*/
|
|
49
|
+
export const ASSET_TYPES = Object.freeze({
|
|
50
|
+
png: "image/png",
|
|
51
|
+
jpg: "image/jpeg",
|
|
52
|
+
jpeg: "image/jpeg",
|
|
53
|
+
gif: "image/gif",
|
|
54
|
+
webp: "image/webp",
|
|
55
|
+
avif: "image/avif",
|
|
56
|
+
svg: "image/svg+xml",
|
|
57
|
+
mp4: "video/mp4",
|
|
58
|
+
webm: "video/webm",
|
|
59
|
+
mp3: "audio/mpeg",
|
|
60
|
+
m4a: "audio/mp4",
|
|
61
|
+
wav: "audio/wav",
|
|
62
|
+
pdf: "application/pdf",
|
|
63
|
+
txt: "text/plain",
|
|
64
|
+
csv: "text/csv",
|
|
65
|
+
json: "application/json",
|
|
66
|
+
docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
|
67
|
+
xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
|
68
|
+
pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
|
|
69
|
+
zip: "application/zip",
|
|
70
|
+
});
|
|
71
|
+
/**
|
|
72
|
+
* Where a Site's app serves the Instance's assets: `<prefix>/_ez/files/<name>`.
|
|
73
|
+
* @type {typeof import("./paths.d.mts").ASSET_PATH}
|
|
74
|
+
*/
|
|
75
|
+
export const ASSET_PATH = "/_ez/files";
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Allowed attachment types by extension: the asset table. Limits are data, loosened by release.
|
|
79
|
+
* @type {typeof import("./paths.d.mts").ATTACHMENT_TYPES}
|
|
80
|
+
*/
|
|
81
|
+
export const ATTACHMENT_TYPES = Object.freeze({ ...ASSET_TYPES });
|
|
82
|
+
/**
|
|
83
|
+
* Where a Site's app takes and serves attachments: `POST <prefix>/_ez/attachments/<table>/<column>?name=<file>`
|
|
84
|
+
* and `GET <prefix>/_ez/attachments/<id>`.
|
|
85
|
+
* @type {typeof import("./paths.d.mts").ATTACHMENT_PATH}
|
|
86
|
+
*/
|
|
87
|
+
export const ATTACHMENT_PATH = "/_ez/attachments";
|
|
88
|
+
/**
|
|
89
|
+
* The content type an attachment gets from its filename's extension, or null when the type is not allowed.
|
|
90
|
+
* @type {typeof import("./paths.d.mts").attachmentContentType}
|
|
91
|
+
*/
|
|
92
|
+
export function attachmentContentType(filename) {
|
|
93
|
+
const m = /\.([A-Za-z0-9]+)$/.exec(filename);
|
|
94
|
+
return m ? (ATTACHMENT_TYPES[m[1].toLowerCase()] ?? null) : null;
|
|
95
|
+
}
|