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 CHANGED
@@ -1,59 +1,63 @@
1
1
  # `@ezship/cli`
2
2
 
3
- The `ez` command and **the contract** — every operation on an Instance or a Site, run
4
- identically by the CLI and the studio. Apache-2.0; requires Node 20 or later.
5
-
6
- - `ez.mjs` — terminal binding: Instance login, primary switching, Site selection, Working Copy on disk.
7
- - `connections.mjs` — shared discovery, identities, primary selection and target/request binding.
8
- - `account.mjs` — `ez tokens` / `ez token revoke`; `editor.mjs` — editor setup written on Clone, Pull and Dev.
9
- - `local-fetch.mjs` — terminal HTTP for `*.localhost`, preserving the Instance origin while connecting to loopback.
10
- - `commands.mjs` (`@ezship/cli/contract`) — every command against the `Workspace` interface, and `ROUTES`: how
3
+ The `ez` command and **the contract**: every operation on an ezship Instance or Site, run identically by the
4
+ CLI and the Studio. Apache-2.0; requires Node 20 or later. `ez help` is the guide to building a Site.
5
+
6
+ ## Signing in
7
+
8
+ `ez login acme` discovers `https://acme.ezship.dev` and signs in with a code emailed to you (`--email
9
+ <address>`, else it asks). With `--password [--username NAME]` it asks for a password instead (or reads it
10
+ from piped stdin, which then needs `--username`); `--browser` approves the login on the platform's page.
11
+
12
+ Each login is a saved connection in `~/.ez/connections.json`. `ez login bravo` saves another one while Acme
13
+ stays primary; `ez logins` lists them, `ez switch bravo` changes the primary, and `--instance acme` targets
14
+ one command. A bound folder always means its own Instance. For local development use `ez login
15
+ http://dev.localhost:5199`; no system DNS change is needed.
16
+
17
+ `ez account [--password]` opens the platform's account page. `ez tokens` and `ez token revoke <id>` list and
18
+ revoke tokens (`--json` supported). `ez logout [--all]` forgets saved credentials; it does not revoke a token.
19
+
20
+ ## The Instance folder
21
+
22
+ `ez clone [<instance>]` pulls every Site you may open into `sites/<folder>/`, named for the Site, and the
23
+ Global Workspace into `global/`; `ez pull --all` refreshes them, following each folder's binding, never its
24
+ name, and moves a folder when its Site is renamed. No Site may be named `global` or `sites`.
25
+
26
+ `ez global <command>` works on the Global Working Copy from a Site's folder. Admins and Builders add Tables,
27
+ nullable columns and indexes to `global/db/schema.sql`; every schema edit regenerates `global/db/types.d.ts`,
28
+ and Site code imports row types from `global/db/types`. Run `ez global check`, then `ez global push`, before a
29
+ Preview or Deploy can create what you added: a push makes published definitions permanent and runs no DDL, and
30
+ a deployed Site keeps its code and Declaration until it is deployed again. Limited Builders read, check and
31
+ preview their own copy.
32
+
33
+ `ez preview` and `ez dev` build with the `global/` beside the Site (or `--global-dir <dir>`, which must be
34
+ pulled for the same Instance and Builder), else with the pushed Global files; a Preview of a retained Version
35
+ uses the pushed ones. `ez dev` watches both copies and uploads after every change; the Preview reloads itself
36
+ after each successful build. `ez check` runs the hosted Pipeline's full checks.
37
+
38
+ ## Editor setup
39
+
40
+ Clone, Pull and `ez dev` write editor setup for VS Code and other TypeScript editors: one root `tsconfig.json`
41
+ extending `.ez/editor/tsconfig.json`, shared by `global/` and every Site folder, with the React, JSX,
42
+ `@ezship/react` and Global declarations and the database row types. No npm install is needed in a Working
43
+ Copy. A standalone Working Copy, a Site with its own `tsconfig.json`, or one using a different `--global-dir`
44
+ keeps its own setup; a custom configuration can extend `./.ez/editor/tsconfig.json`. Editor metadata never
45
+ enters status, Push or Preview, and the declarations follow the installed CLI release.
46
+
47
+ ## What is in the package
48
+
49
+ - `ez.mjs`: the terminal binding: login, the primary, Site selection, Working Copies on disk.
50
+ - `connections.mjs`: discovery, saved identities, the primary, target and request binding, the contract
51
+ number.
52
+ - `commands.mjs` (`@ezship/cli/contract`): every command against the `Workspace` interface, and `ROUTES`, how
11
53
  each remote method reaches the API (`httpWorkspace` for clients, `matchRoute` for the platform).
12
- - `schema.mjs` (`@ezship/cli/schema`) — App Database rule table, `db/schema.sql` parser, deploy planner.
13
- - `types.d.mts` (`@ezship/cli/types`) — the HTTP API's shapes.
14
- - `update-check.mjs` — once a day, whether npm has a newer release; `ez` then says so on standard error after
15
- the command (docs/adr/0111). `EZ_NO_UPDATE_CHECK=1` or `CI` turns it off.
16
-
17
- Plain JavaScript, zero runtime dependencies, Node 20+, no build. Tests: `npm test` (`bun test`).
18
-
19
- Account access: `ez login <instance or URL> --password [--username NAME]` prompts for a password (or reads it
20
- from piped stdin, which then requires `--username`); `--browser` opens the
21
- platform approval page. `ez account [--password]` opens platform account management. `ez tokens` and
22
- `ez token revoke <id>` list/revoke tokens (`--json` supported). `ez logout [--all]` forgets saved credentials;
23
- it does not revoke issued tokens.
24
-
25
- Preview includes the Instance folder's `global/` Working Copy, or `--global-dir <dir>`. Its pulled metadata must match
26
- the Instance uid/address and Builder. Without it, platform uses pushed global files. Preview pages reload
27
- automatically after successful builds while visible. `ez dev` watches both
28
- copies. Retained-Version previews use pushed global files.
29
-
30
- `ez global <command>` operates on that Global Working Copy from a Site. Admins and Builders can add Tables,
31
- nullable columns and indexes to `db/schema.sql`; schema edits regenerate global `db/types.d.ts`.
32
- Import row types from `global/db/types`. Run `ez global check`, then `ez global push` before Preview
33
- or Deploy can materialize additions. Push makes published definitions permanent but performs no DDL.
34
- Existing deployments keep their code and Declaration until redeployed. Admins and Builders push every global
35
- file; Limited Builders read, check and preview their own copy. See [the transition guide](../../docs/adr/0021-global-schema-integration.md) for existing Sites.
36
-
37
- `ez login acme` discovers `https://acme.ezship.dev`. `ez login bravo` saves another connection while Acme
38
- stays primary. `ez logins` lists them; `ez switch bravo` changes the primary; `--instance acme` targets one
39
- command. Bound folders remain on their Instance. Remote commands can target another connection; file
40
- commands need its own `--dir`. Studio uses the same selection contract. Connections live in
41
- `~/.ez/connections.json`; legacy files require explicit `ez adopt` after fresh Instance sign-in.
42
- For local development use `ez login http://dev.localhost:5199`; no system DNS change is needed.
43
-
44
- `ez clone [<instance>]` pulls every Site into `sites/<folder>/`, named for the Site, and the Global Workspace
45
- into `global/` (see `docs/adr/0034` and `0079`); `ez pull --all` refreshes them, following each folder's binding,
46
- never its name, and moves a Site folder from before `sites/` into it. No Site may be named `global` or `sites`.
47
-
48
- Clone, Pull and `ez dev` automatically prepare React, JSX and `@ezship/react` declarations for
49
- VS Code and other TypeScript editors, with Global imports and database row types. No npm install
50
- is needed in a Working Copy. To repair an older Instance checkout, update the CLI and run
51
- `ez pull --all`; even folders skipped for unpushed changes receive editor setup.
52
- Cloned Instances share one root `tsconfig.json` extending `.ez/editor/tsconfig.json`, with one
53
- declaration bundle for all their Site folders and `global/`. Pull and Dev inside a Site refresh
54
- the shared setup too. Old generated per-folder configs and declarations are removed automatically;
55
- custom configs and unpushed files are preserved. Unrelated folders are excluded from the project.
56
- A standalone Working Copy, a Site with a custom config, or one using a different `--global-dir`
57
- keeps its own editor setup. Custom configurations can extend `./.ez/editor/tsconfig.json` to use
58
- the generated settings. Editor metadata never enters status, Push or Preview.
59
- Declarations follow the installed CLI release. `ez check` runs the hosted Pipeline's full checks.
54
+ - `schema.mjs` (`@ezship/cli/schema`): the App Database rule table, the `db/schema.sql` parser and the schema
55
+ planner.
56
+ - `types.d.mts` (`@ezship/cli/types`): the HTTP API's shapes.
57
+ - `account.mjs`: `ez tokens` and `ez token revoke`; `editor.mjs`: the editor setup; `bindings.mjs`: where a
58
+ folder's binding lives.
59
+ - `local-fetch.mjs`: HTTP for `*.localhost`, keeping the Instance origin while connecting to loopback.
60
+ - `update-check.mjs`: at most once a day, whether npm has a newer release; `ez` then says so on standard error
61
+ after the command. `EZ_NO_UPDATE_CHECK=1` or `CI` turns it off.
62
+
63
+ Plain JavaScript, zero runtime dependencies, no build. Tests: `bun run test`.
package/access.d.mts CHANGED
@@ -4,7 +4,7 @@ import type { Declaration, Table } from "./schema.d.mts";
4
4
  /** A value a condition compares with. */
5
5
  export type Literal = string | number | boolean;
6
6
 
7
- /** A condition on the governed row (docs/adr/0098). */
7
+ /** A condition on the governed row (docs/adr/0225). */
8
8
  export type Condition =
9
9
  | { kind: "or"; items: Condition[] }
10
10
  | { kind: "and"; items: Condition[] }
@@ -43,12 +43,12 @@ export type Rule =
43
43
  export type Access = {
44
44
  tables: Record<string, { read?: Rule; write?: Rule }>;
45
45
  /**
46
- * The active scope (docs/adr/0098): queries of Tables with `column` keep to the value the viewer chose,
46
+ * The active scope (docs/adr/0225): queries of Tables with `column` keep to the value the viewer chose,
47
47
  * held in Session State as `key`, among the values `lookup` gives them. Convenience, never authority.
48
48
  */
49
49
  scope?: Scope;
50
50
  /**
51
- * The declared groups (docs/adr/0101): each group app code may assign, with the groups holding it
51
+ * The declared groups (docs/adr/0225): each group app code may assign, with the groups holding it
52
52
  * confers (sorted). Absent when the file declares none.
53
53
  */
54
54
  groups?: Record<string, string[]>;
@@ -106,7 +106,7 @@ export function accessChanges(
106
106
  next: Access | null,
107
107
  nextDecl: Declaration,
108
108
  ): AccessChange[];
109
- /** A Member's groups: assigned ones plus everything they imply, transitively, sorted (docs/adr/0101). */
109
+ /** A Member's groups: assigned ones plus everything they imply, transitively, sorted (docs/adr/0225). */
110
110
  export function impliedGroups(
111
111
  access: Access | null | undefined,
112
112
  assigned: readonly string[],
package/access.mjs CHANGED
@@ -1,5 +1,5 @@
1
- // Row access (docs/adr/0098): who reads and writes which rows of each Table, declared once in the Global
2
- // Workspace's db/access.sql and enforced by the Host for every artifact (a Live definition, docs/adr/0096).
1
+ // Row access (docs/adr/0225): who reads and writes which rows of each Table, declared once in the Global
2
+ // Workspace's db/access.sql and enforced by the Host for every artifact (a Live definition, docs/adr/0224).
3
3
  // Zero dependencies, plain JavaScript, Node 20+ and the browser. The parser, the validation against the
4
4
  // published schema, the SQL a condition compiles to and the printed form all live here, so the Host, `ez`
5
5
  // and the Framework cannot disagree about what a rule means.
@@ -128,10 +128,10 @@ class Cursor {
128
128
  const SHAPE = `${ACCESS_FILE} holds READ <table> WHERE <condition>;, WRITE <table> WHERE <condition>;, WRITE <table> BY functions;, READ|WRITE <table> BY none; (each naming one Table or several, separated by commas), GROUP <name> [IMPLIES <name>, ...]; and one SCOPE`;
129
129
  const GROUP_SHAPE =
130
130
  "GROUP <name> [IMPLIES <name>, ...]; declares a group app code may assign and the groups holding it confers";
131
- /** Why access.sql cannot declare or imply a Host group (docs/adr/0110). @param {string} name */
131
+ /** Why access.sql cannot declare or imply a Host group (docs/adr/0225). @param {string} name */
132
132
  const RESERVED_DECLARED = (name) =>
133
133
  `${name}: ez- groups are the Host's (${RESERVED_GROUPS.join(" for the Instance's Admins, ")} for every Builder); nothing declares, implies or assigns them`;
134
- /** At most this many GROUP statements (docs/adr/0101), the roster's own cap on group names. */
134
+ /** At most this many GROUP statements (docs/adr/0225), the roster's own cap on group names. */
135
135
  const MAX_DECLARED = 50;
136
136
  const SCOPE_SHAPE =
137
137
  "SCOPE <column> FROM <savedKey> IN my(<table>.<column> [WHERE ...]); names the scoped column, the Session State key holding the active value, and where its values come from";
@@ -172,7 +172,7 @@ function parse(sql) {
172
172
  const verb = c.next();
173
173
  const op = verb.text.toUpperCase();
174
174
  if (op === "GROUP" && verb.kind === "word") {
175
- // GROUP <name> [IMPLIES <name>, ...]: a group app code may assign (docs/adr/0101).
175
+ // GROUP <name> [IMPLIES <name>, ...]: a group app code may assign (docs/adr/0225).
176
176
  const name = c.next();
177
177
  if (!name || name.kind !== "word" || !GROUP.test(name.text))
178
178
  return {
@@ -206,7 +206,7 @@ function parse(sql) {
206
206
  continue;
207
207
  }
208
208
  if (op === "SCOPE") {
209
- // SCOPE <column> FROM <Saved key> IN my(<table>.<column> ...): the active scope (docs/adr/0098).
209
+ // SCOPE <column> FROM <Saved key> IN my(<table>.<column> ...): the active scope (docs/adr/0225).
210
210
  if (access.scope) return { error: "an Instance declares one SCOPE", line: verb.line };
211
211
  const column = c.next();
212
212
  if (!column || column.kind !== "word" || !NAME.test(column.text) || !c.takeWord("FROM"))
@@ -227,7 +227,7 @@ function parse(sql) {
227
227
  }
228
228
  if (verb.kind !== "word" || (op !== "READ" && op !== "WRITE"))
229
229
  return { error: `unexpected ${verb.text}: ${SHAPE}`, line: verb.line };
230
- // One Table or several: READ a, b, c WHERE ... is one rule per Table (docs/adr/0101).
230
+ // One Table or several: READ a, b, c WHERE ... is one rule per Table (docs/adr/0225).
231
231
  /** @type {Token[]} */
232
232
  const names = [];
233
233
  do {
@@ -427,7 +427,7 @@ function parseAtom(c) {
427
427
  }
428
428
 
429
429
  /**
430
- * A row-free condition (docs/adr/0098): what a page's `access` or a server function's `{ access }` says,
430
+ * A row-free condition (docs/adr/0225): what a page's `access` or a server function's `{ access }` says,
431
431
  * `group(<name>)` atoms with AND, OR and parentheses. Nothing here reads a row.
432
432
  * @type {typeof import("./access.d.mts").parseGate}
433
433
  */
@@ -472,7 +472,7 @@ export function gateAllows(cond, groups) {
472
472
  }
473
473
  }
474
474
 
475
- // ---- declared groups (docs/adr/0101) --------------------------------------------------------------------
475
+ // ---- declared groups (docs/adr/0225) --------------------------------------------------------------------
476
476
 
477
477
  /**
478
478
  * A Member's groups: the ones they were assigned plus every group those imply, transitively, sorted. What
@@ -604,7 +604,7 @@ export function effectiveRule(access, table, def, op) {
604
604
  const declared = access?.tables[table]?.[op];
605
605
  if (declared) return declared;
606
606
  const policy = op === "read" ? def.read : def.write;
607
- // An unknown stored policy (a retired `public`, docs/adr/0036) admits no one.
607
+ // No policy is `member`; `none` admits no one.
608
608
  return policy === undefined || policy === "member" ? { kind: "member" } : { kind: "none" };
609
609
  }
610
610
 
@@ -767,7 +767,7 @@ function checkCondition(cond, table, def, decl, access, strict = true) {
767
767
 
768
768
  // ---- SQL ------------------------------------------------------------------------------------------------
769
769
 
770
- /** A literal in storage form: booleans as 0/1 (docs/adr/0007). @param {Literal} v */
770
+ /** A literal in storage form: booleans as 0/1 (docs/adr/0217). @param {Literal} v */
771
771
  const stored = (v) => (typeof v === "boolean" ? (v ? 1 : 0) : v);
772
772
 
773
773
  /**
@@ -877,7 +877,7 @@ export function conditionColumns(cond) {
877
877
  const ALWAYS_STORED = ["id", "created_at", "created_by", "updated_at", "updated_by"];
878
878
 
879
879
  /**
880
- * The rules as the App Database can answer them now (docs/adr/0156). A column no Preview or Deploy has added
880
+ * The rules as the App Database can answer them now (docs/adr/0225). A column no Preview or Deploy has added
881
881
  * yet holds NULL in every row, so an atom that reads one is replaced by what NULL gives it: `IS NULL` always
882
882
  * passes (an AND of nothing), every other test never does (an OR of nothing), and a lookup through a missing
883
883
  * Table or column finds no value. A scope whose lookup cannot be read yet is left out: it only narrows.
@@ -1008,7 +1008,7 @@ export const printRule = (rule) =>
1008
1008
  : `BY ${rule.kind}`;
1009
1009
 
1010
1010
  /**
1011
- * The rules a Global Push changes (docs/adr/0096): every Table and operation whose effective rule prints
1011
+ * The rules a Global Push changes (docs/adr/0224): every Table and operation whose effective rule prints
1012
1012
  * differently under the next schema and access file than under the published ones.
1013
1013
  * @type {typeof import("./access.d.mts").accessChanges}
1014
1014
  */
package/account.mjs CHANGED
@@ -1,4 +1,5 @@
1
- // Host account operations are outside the Instance route table (ADRs 0009 and 0015).
1
+ // Host account operations are outside the Instance route table (ADRs 0204 and 0244).
2
+ import { CONTRACT, CONTRACT_HEADER } from "./connections.mjs";
2
3
  /** @type {typeof import("./account.d.mts").ACCOUNT_OPERATIONS} */
3
4
  export const ACCOUNT_OPERATIONS = Object.freeze([
4
5
  "identity",
@@ -18,12 +19,7 @@ export async function runAccountCommand(send, argv) {
18
19
  const words = argv.filter((a) => a !== "--json");
19
20
  let data;
20
21
  if (words[0] === "tokens" && words.length === 1) data = await send("GET", "/api/tokens");
21
- else if (
22
- words[0] === "token" &&
23
- (words[1] === "revoke" || words[1] === "rm") &&
24
- words[2] &&
25
- words.length === 3
26
- )
22
+ else if (words[0] === "token" && words[1] === "revoke" && words[2] && words.length === 3)
27
23
  data = await send("DELETE", "/api/tokens/" + encodeURIComponent(words[2]));
28
24
  else throw new Error("Usage: ez tokens [--json] | ez token revoke <id> [--json]");
29
25
  if (argv.includes("--json")) return JSON.stringify(data);
@@ -67,7 +63,12 @@ async function sessionLogin(api, path, input, name, send) {
67
63
  send(api + path, {
68
64
  method: "POST",
69
65
  redirect: "manual",
70
- headers: { "content-type": "application/json", origin: api, ...(cookie ? { cookie } : {}) },
66
+ headers: {
67
+ "content-type": "application/json",
68
+ origin: api,
69
+ [CONTRACT_HEADER]: String(CONTRACT),
70
+ ...(cookie ? { cookie } : {}),
71
+ },
71
72
  body: JSON.stringify(body),
72
73
  });
73
74
  /** @param {Response} res */
package/bindings.mjs CHANGED
@@ -1,13 +1,14 @@
1
- // Where a Working Copy's binding lives (ADR 0085). In an Instance folder the folder holds no `.ez/`: the
1
+ // Where a Working Copy's binding lives (ADR 0205). In an Instance folder the folder holds no `.ez/`: the
2
2
  // Instance folder's `.ez/` keeps `sites/<folder>.json` per Site folder and `global.json`, keyed by folder name.
3
3
  // A standalone Working Copy (a worktree, a Site pulled anywhere else) keeps its own `.ez/pulled.json`.
4
- import { mkdir, readFile, rename, rmdir, unlink, writeFile } from "node:fs/promises";
4
+ import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
5
5
  import { basename, dirname, join, resolve } from "node:path";
6
6
  import { GLOBAL_ID, SITES_FOLDER } from "./commands.mjs";
7
7
 
8
8
  /**
9
9
  * The Instance folder a Working Copy belongs in: `<root>/sites/<folder>` for a Site and `<root>/global` for the
10
- * Global Workspace (ADR 0079). A Site folder directly in its Instance folder predates `sites/` and still counts.
10
+ * Global Workspace (ADR 0205). Any other folder's is its parent, so a standalone Working Copy finds the
11
+ * `global/` beside it.
11
12
  * @param {string} dir
12
13
  */
13
14
  export function instanceFolderOf(dir) {
@@ -71,7 +72,7 @@ export const sameInstance = (instance, workingCopy) =>
71
72
  * The file that holds `dir`'s binding now: the Instance folder's, else the folder's own; null when neither exists.
72
73
  * @param {string} dir @returns {Promise<string | null>}
73
74
  */
74
- export async function bindingFile(dir) {
75
+ async function bindingFile(dir) {
75
76
  for (const file of [sharedFile(dir)?.file, ownFile(dir)])
76
77
  if (file && (await readJson(file)) !== null) return file;
77
78
  return null;
@@ -88,7 +89,7 @@ export async function readBinding(dir) {
88
89
 
89
90
  /**
90
91
  * Writes `dir`'s binding: into the Instance folder's `.ez/` when `dir` is one of its Working Copies and the binding
91
- * is for its Instance, removing the folder's own copy; into the folder's own `.ez/` otherwise.
92
+ * is for its Instance; into the folder's own `.ez/` otherwise.
92
93
  * @param {string} dir @param {Record<string, unknown> & {uid?: string, app?: string, instance?: string}} binding
93
94
  */
94
95
  export async function writeBinding(dir, binding) {
@@ -99,29 +100,11 @@ export async function writeBinding(dir, binding) {
99
100
  : ownFile(dir);
100
101
  await mkdir(dirname(home), { recursive: true });
101
102
  await writeFile(home, JSON.stringify(binding, null, 2) + "\n");
102
- if (home !== ownFile(dir)) await removeOwn(dir);
103
- }
104
-
105
- /** @param {string} dir */
106
- async function removeOwn(dir) {
107
- await unlink(ownFile(dir)).catch(() => {});
108
- // Only an empty `.ez/` goes; a standalone editor project kept under it stays (ADR 0038).
109
- await rmdir(dirname(ownFile(dir))).catch(() => {});
110
- }
111
-
112
- /**
113
- * Moves a folder's own binding into its Instance folder, unchanged, when that is where it belongs.
114
- * @param {string} dir
115
- */
116
- export async function adoptBinding(dir) {
117
- const own = await readJson(ownFile(dir));
118
- const shared = sharedFile(dir);
119
- if (!own || !shared || (await readJson(shared.file)) !== null) return;
120
- if (sameInstance(await instanceBinding(shared.root), own)) await writeBinding(dir, own);
121
103
  }
122
104
 
123
105
  /**
124
- * Renames a Working Copy folder inside its Instance folder and carries its binding along.
106
+ * Renames a Working Copy folder inside its Instance folder and carries its binding along (a folder's own
107
+ * binding moves with the folder).
125
108
  * @param {string} from @param {string} to
126
109
  */
127
110
  export async function moveWorkingCopy(from, to) {
@@ -129,8 +112,7 @@ export async function moveWorkingCopy(from, to) {
129
112
  const binding = file ? await readJson(file) : null;
130
113
  await mkdir(dirname(to), { recursive: true });
131
114
  await rename(from, to);
132
- if (file === ownFile(from)) return adoptBinding(to);
133
- if (!file) return;
115
+ if (!file || file === ownFile(from)) return;
134
116
  await unlink(file);
135
117
  await writeBinding(to, binding);
136
118
  }