ezship 0.1.10 → 0.1.12

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,11 +1,59 @@
1
- # `ezship`
1
+ # `@ezship/cli`
2
2
 
3
- The `ez` command for [ezship](https://ezship.dev). This package is an alias for
4
- [`@ezship/cli`](https://www.npmjs.com/package/@ezship/cli); both install the same `ez`.
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
5
 
6
- ```sh
7
- npm install -g ezship
8
- ez login <instance>
9
- ```
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
11
+ 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.
10
16
 
11
- Requires Node 20 or later.
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.
package/access.d.mts ADDED
@@ -0,0 +1,120 @@
1
+ // Hand-written declarations for cli/access.mjs. Keep in step with the JSDoc there.
2
+ import type { Declaration, Table } from "./schema.d.mts";
3
+
4
+ /** A value a condition compares with. */
5
+ export type Literal = string | number | boolean;
6
+
7
+ /** A condition on the governed row (docs/adr/0098). */
8
+ export type Condition =
9
+ | { kind: "or"; items: Condition[] }
10
+ | { kind: "and"; items: Condition[] }
11
+ | { kind: "owner" }
12
+ | { kind: "group"; name: string }
13
+ | { kind: "me"; column: string }
14
+ | { kind: "eq"; column: string; value: Literal }
15
+ | { kind: "null"; column: string; not: boolean }
16
+ | {
17
+ kind: "my";
18
+ column: string;
19
+ table: string;
20
+ select: string;
21
+ where: LookupCondition[];
22
+ /** The lookup Table's MEMBER column; filled by checkAccess, "" straight from the parser. */
23
+ member: string;
24
+ };
25
+
26
+ /** A condition on a lookup Table's rows inside `my(...)`. */
27
+ export type LookupCondition =
28
+ | { kind: "eq"; column: string; value: Literal }
29
+ | { kind: "null"; column: string; not: boolean }
30
+ | { kind: "has"; column: string; value: string };
31
+
32
+ /**
33
+ * Who may perform an operation: every active Member (the schema's `member` policy), a condition, server code
34
+ * only (writes), or Builders only.
35
+ */
36
+ export type Rule =
37
+ | { kind: "member" }
38
+ | { kind: "where"; cond: Condition }
39
+ | { kind: "functions" }
40
+ | { kind: "none" };
41
+
42
+ /** db/access.sql: each named Table's READ and WRITE statements. */
43
+ export type Access = {
44
+ tables: Record<string, { read?: Rule; write?: Rule }>;
45
+ /**
46
+ * The active scope (docs/adr/0098): queries of Tables with `column` keep to the value the viewer chose,
47
+ * held in Session State as `key`, among the values `lookup` gives them. Convenience, never authority.
48
+ */
49
+ scope?: Scope;
50
+ /**
51
+ * The declared groups (docs/adr/0101): each group app code may assign, with the groups holding it
52
+ * confers (sorted). Absent when the file declares none.
53
+ */
54
+ groups?: Record<string, string[]>;
55
+ };
56
+ export type Scope = {
57
+ column: string;
58
+ key: string;
59
+ lookup: Extract<Condition, { kind: "my" }>;
60
+ };
61
+
62
+ /** The viewer a condition is compiled for: `me` is their MEMBER value, null signed out or in a job. */
63
+ export type AccessViewer = { me: string | null; groups: readonly string[] };
64
+
65
+ /** One operation's effective rule changed by a Global Push, both sides printed. */
66
+ export type AccessChange = { table: string; op: "read" | "write"; from: string; to: string };
67
+
68
+ export const ACCESS_FILE: "db/access.sql";
69
+ /** A page's or server function's row-free access condition: group(<name>) with AND, OR, parentheses. */
70
+ export function parseGate(text: string): { cond: Condition } | { error: string };
71
+ export function gateAllows(cond: Condition, groups: readonly string[]): boolean;
72
+ export function parseAccess(sql: string): { access: Access } | { error: string; line: number };
73
+ export function checkAccess(
74
+ sql: string,
75
+ decl: Declaration,
76
+ ): { access: Access } | { error: string; line: number };
77
+ export function effectiveRule(
78
+ access: Access | null | undefined,
79
+ table: string,
80
+ def: Table,
81
+ op: "read" | "write",
82
+ ): Rule;
83
+ export function compileCondition(
84
+ cond: Condition,
85
+ viewer: AccessViewer,
86
+ instance: string,
87
+ column?: (name: string) => { sql: string; binds: (string | number | null)[] },
88
+ ): { sql: string; binds: (string | number | null)[] };
89
+ export function conditionColumns(cond: Condition): string[];
90
+ export function lookupSelect(
91
+ lookup: Extract<Condition, { kind: "my" }>,
92
+ me: string,
93
+ instance: string,
94
+ ): { sql: string; binds: (string | number | null)[] };
95
+ export function referencedColumns(access: Access): { table: string; column: string }[];
96
+ export function printScope(access: Access | null | undefined): string | null;
97
+ export function printCondition(cond: Condition): string;
98
+ export function printRule(rule: Rule): string;
99
+ export function accessChanges(
100
+ before: Access | null,
101
+ beforeDecl: Declaration,
102
+ next: Access | null,
103
+ nextDecl: Declaration,
104
+ ): AccessChange[];
105
+ /** A Member's groups: assigned ones plus everything they imply, transitively, sorted (docs/adr/0101). */
106
+ export function impliedGroups(
107
+ access: Access | null | undefined,
108
+ assigned: readonly string[],
109
+ ): string[];
110
+ /** The groups app code may assign: the declared ones, sorted. */
111
+ export function declaredGroups(access: Access | null | undefined): string[];
112
+ /** The GROUP statements, normalized, or null for none. */
113
+ export function printGroups(access: Access | null | undefined): string | null;
114
+ /** The groups whose holders differ between two files' declarations. */
115
+ export function groupsAffected(
116
+ before: Access | null | undefined,
117
+ next: Access | null | undefined,
118
+ ): string[];
119
+ /** The groups a rule tests. */
120
+ export function ruleGroups(rule: Rule): string[];