ezship 0.1.11 → 0.1.13
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 +56 -8
- package/access.d.mts +120 -0
- package/access.mjs +987 -0
- package/account.d.mts +19 -0
- package/account.mjs +91 -0
- package/bindings.mjs +136 -0
- package/commands.d.mts +672 -0
- package/commands.mjs +8098 -0
- package/connections.d.mts +61 -0
- package/connections.mjs +312 -0
- package/cron.d.mts +17 -0
- package/cron.mjs +124 -0
- package/documents.d.mts +26 -0
- package/documents.mjs +242 -0
- package/editor-types.json.gz +0 -0
- package/editor.mjs +212 -0
- package/ez.mjs +1300 -2
- package/local-fetch.mjs +57 -0
- package/package.json +82 -6
- package/schema.d.mts +369 -0
- package/schema.mjs +3099 -0
- package/session.d.mts +20 -0
- package/session.mjs +142 -0
- package/shape.d.mts +14 -0
- package/shape.mjs +312 -0
- package/signup.d.mts +11 -0
- package/signup.mjs +42 -0
- package/types.d.mts +879 -0
- package/update-check.mjs +105 -0
- package/workflow.d.mts +63 -0
- package/workflow.mjs +450 -0
package/README.md
CHANGED
|
@@ -1,11 +1,59 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@ezship/cli`
|
|
2
2
|
|
|
3
|
-
The `ez` command
|
|
4
|
-
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
ez
|
|
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
|
-
|
|
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[];
|