@lotics/cli 0.318.50 → 0.320.0

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.
@@ -1,252 +0,0 @@
1
- # Building an app, end to end
2
-
3
- The other references here describe **grammars** — what a table document or an app tree may state, what a tool takes. This
4
- one describes the **sequence**: the order the steps go in, and why. Read it once for the shape, then
5
- reach for the area doc (`lotics docs`) whenever you need the detail.
6
-
7
- **The live app is the only edit surface.** Every change to an app — applying a tree, deploying a
8
- build, setting one query or workflow — mints a new version of it. To go back, apply the earlier tree
9
- again (or deploy the earlier source). Nothing about an app lives in a local directory the platform
10
- reads back.
11
-
12
- **Going back restores the app, not the data.** A table change, and every row a workflow wrote while
13
- you tried it, stay where they are. Try a write on a throwaway record.
14
-
15
- ---
16
-
17
- ## 1 — Two kinds of app
18
-
19
- - **An app stated as a tree** — the default, and the right one for almost every job. The tree (a
20
- JSON file, one per app) is a List of one table, whose rows are recognised by the
21
- table's own `records`, and the page its rows open (`pages`), with the Lists and Sheets that stand beside it at the root as peers (which a change may add at any time, each a View of its own, shown to whoever the app is shared with): its columns and filters, its Sections in the order its work
22
- reaches them, its Acts and the Checks that guard them (`lotics docs reference/app-tree`,
23
- `reference/list-node`, `reference/section-node`, `reference/act-node`, `reference/check-node`). The platform
24
- compiles each app and draws it with the runtime every such app shares, so how each piece looks is
25
- the platform's, one way per concept, and no prop changes it. Every write the app makes is a
26
- generated workflow that re-checks on the server what the tables state.
27
- - **A custom-code app** — your own project, for a surface the tree's components cannot state. Its UI
28
- library, components, styling, state, bundler, tests and lint are yours; it reads and writes through
29
- `@lotics/app-sdk` (queries, workflows, files, AI).
30
-
31
- ## 2 — Clarify what is being asked, before designing it
32
-
33
- **A metric name is not a definition.** "Revenue", "in stock", "active", "overdue" — each is a
34
- business rule the person asking owns, and the cost of guessing is a screen that is confidently
35
- wrong. Ask until there is no ambiguity left:
36
-
37
- - Which rows count, keyed off which field — a date, a status, a flag?
38
- - Does the same metric need a **different rule per table**? One table may key off a date and
39
- another off a status; one rule rarely covers both.
40
- - Snapshot or flow? "Current stock" is as-of-now; "revenue this month" is a window. They compile
41
- to different filters.
42
- - If the data cannot support the definition asked for — the field simply is not there — **say so
43
- and show the options.** Silently substituting a near-miss produces a number nobody can trace.
44
-
45
- This is the step that gets skipped under time pressure, and it is the only one whose mistakes are
46
- invisible in review: every later artifact is correct with respect to the wrong definition.
47
-
48
- ## 3 — The data model, before any app
49
-
50
- Get this wrong and nothing above it can be precise. Each kind of thing is its own table with links into
51
- the spine; attributes and evidence are fields on their owner. A single table with a `type` column
52
- standing in for three kinds of thing collapses the distinctions every later query needs.
53
-
54
- **Verify real VALUES, never just that a field exists.** `lotics run query_records` a sample and
55
- look at fill rates — a field that is present and empty on 90% of rows will not support the screen
56
- you are about to design.
57
-
58
- **That includes imagery.** If the thing has a likeness — a product, a property, a vehicle, a
59
- person — its picture is the strongest identifier a register row can carry, and an empty image field
60
- is a data gap to fill before you design around it: `lotics file upload`, then `update_records`.
61
-
62
- **Match on ids and option aliases, never on rendered text.** Resolve a name to its `rec_…` or its option alias
63
- once, at the boundary, and compare those. Treat an unresolved name as UNKNOWN, never as a wildcard.
64
-
65
- **How the tables RELATE, and one fact in one column, is `lotics docs data_model`** — read it before designing a
66
- schema; those decisions outlive any one app.
67
-
68
- ## 4 — An app stated as a tree
69
-
70
- Tables first, then apps. `set_tables` takes a list of table documents, one or many, and writes them all or
71
- none; `set_app` takes one app per call. Each creates when it is given no id and edits when it is given one.
72
-
73
- ```
74
- lotics docs reference # the keys of a table document and the app tree's components, with a worked example
75
- lotics docs design # the treatment per kind of row
76
- lotics run set_tables @tables.json # one call, every table: {"tables": [...]}
77
- lotics run set_app @orders.call.json # one app: {"body": <the App tree>} to create (add "dry_run": true to check)
78
- lotics app apply orders.app.json --check # the same tool from a bare tree file: what would refuse it, writing nothing
79
- lotics app apply orders.app.json # no app known: creates it; known: edits it to the file
80
- lotics app pull <app_id> # the app's tree, as ./<name>.app.json
81
- ```
82
-
83
- A new workspace is built in one order: one `set_tables` call with the tables, then every `set_app`
84
- call, then fixes. One call carries at most 50 tables, 200 first rows a table, and 2000 rows and 2000
85
- documents in all; a workspace of more tables is built in further calls, each naming the tables already made by
86
- their ids.
87
-
88
- A table is a document: its `fields` are keyed by alias, and a link field names the table it
89
- points at by id, or by the `ref` of another table of the same call, and states `multi`. A
90
- two-way link states `pair` on one table, as `true` or as a free alias, and the partner is made on the other; a many-to-many link states both sides. A table is edited by an RFC 7396 merge patch of its document:
91
- what the patch leaves alone is left alone and `null` deletes. `dry_run` checks the call and writes
92
- nothing; a refusal lists everything wrong in it at once.
93
-
94
- The App node is the app: its `name`, `description`, `icon` and `color` are props of it, and no other input of
95
- `set_app` states them. It names the tables and templates it uses by their aliases (an entity is a table's alias, a `template` a template's alias);
96
- `set_app` fills the `tables` and `templates` maps by id from them and `get_app` shows aliases (`lotics docs reference/app-node`).
97
- Who reads which rows is the app's `rows` (§ Who reads which rows, below). A call that creates
98
- is `{"body": <the App tree>}`; one that changes a part is `{"app_id": "app_…", "nodes": {"<address>": <patch>}}`,
99
- each address a node's path of keys (`get_app` prints every one), a patch a JSON merge patch of that node's props
100
- and `null` removing the node; the App's own props change through `body`. A call stating `base_version_id` — the
101
- version you read — is refused when the app has moved on. The old body grammar (`register`, `record`, `acts`,
102
- `edits`) is refused with a sentence pointing here.
103
-
104
- A tree states what it means once: a statement equal to what the runtime draws anyway (a column the row already shows) is kept,
105
- drawn once and noted, while a statement that conflicts is refused. A register List's `label` is the register's heading in the app's lists; its rows are named by the table's own label and singular.
106
- `type` may be omitted, and a Section, Side or Page
107
- without a `key` is keyed by its title's slug, written once and kept.
108
-
109
- `app apply` with no app known creates one from the file, named by the tree's `name`, and records its id and
110
- version in `<file>.lotics.json` (`app pull` writes the same file), so the next apply of that file edits that
111
- app; `--app <app_id>` names it instead, and is refused for a file whose record names another app. A known app
112
- is read first and only what the file changes is sent, as a JSON merge patch (RFC 7396): a key the file drops
113
- is removed, a list is replaced whole, and what the file leaves alone is left alone. A file pulled at a
114
- version the app has since left is refused, naming the version: pull the current tree into another path and
115
- carry your edits over. Applying a tree the app already has mints nothing.
116
- `--check` sends the same change as `dry_run`: what would refuse the tree, the notes on it, and the permissions the
117
- write would grant and remove, writing nothing. Every write's answer states those permissions: the saves, adds,
118
- Deletes and act writes the new tree grants and removes, from the previous tree to the new one.
119
-
120
- **What the tree leaves out is drawn, never stored.** The answer shows a treatment the rows call for that the tree leaves out —
121
- Readings over its rows, a record's Sections, an Act per status move, a picture where its rows hold photos
122
- (`lotics docs design`) — and the tree states the ones the job needs. What it states with one fix, the write places
123
- and says (`lotics docs reference/changing-an-app`); edit only the difference.
124
-
125
- **The tree changes after the app exists, and applying it again is how it lands.** Pull the tree, edit
126
- the file, apply it; or send `nodes` for one part. An Act whose write the tree cannot say names its own `workflow`; that workflow's code is
127
- the live one, and `lotics run set_workflow` changes it. A job no press starts — an agent or a
128
- service handing the app a file or a list of rows — is a Workflow node the app declares
129
- (`lotics docs reference/workflow-node`): the node states what it takes and hands back, and `lotics run
130
- set_workflow` sets its code with `inputs` and `outputs` left out of its `on({ type: "app", ... })` header.
131
-
132
- **What a person reads and does in the app, an agent reads and does through it.** Writing the tree generates a
133
- query for every List, record, child List and figure the screen reads, and a workflow for every add, edit,
134
- removal and act — `lotics run get_app` lists them, and `lotics docs agent_surface` names each
135
- family and how it is called. A question the screen never asks is a Query node the app declares
136
- (`lotics docs reference/query-node`), beside its Workflow nodes. Both are part of the design: `lotics docs
137
- agent_surface`, § Declaring more.
138
-
139
- ### Who reads which rows
140
-
141
- An app runs with its owner's access, and the people it is shared with need the app alone, never its tables. Who of them
142
- reads which rows is the app's `rows`, one rule per table in the grammar of a table's `read_scope` (`lotics docs reference/read-scope`); it narrows
143
- the app's screens, its queries and workflows called through it (`run_app_query`, `run_app_workflow`), its acts and its
144
- workflow bodies alike, and a record id a caller passes is refused where the rule hides the row. State a rule only where
145
- people differ; a table with none is read whole by everyone the app is shared with.
146
-
147
- | The business says | The app states |
148
- |---|---|
149
- | Everyone on the team sees every order | nothing |
150
- | Each rep sees only their own deals | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }] } }` |
151
- | Reps see their own deals; managers see all | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }, { "member_of": "<managers group id>" }] } }` |
152
- | Each branch manager sees their branch's orders | `"rows": { "order": { "any": [{ "through": ["branch"], "field": "manager", "is": "self" }] } }` |
153
- | Each employee sees only their own payslips; HR sees all | two apps: one stating `"payslip": { "any": [{ "field": "employee", "is": "self" }] }`, one for HR stating none |
154
- | Team leads see people, not salaries | an app that draws no salary field — what it does not show, no one reads through it |
155
-
156
- A child read under a ruled row states its own rule, through its link to the parent; only a status history inherits.
157
- An admin and the app's owner are narrowed like anyone, and the write says so when a rule hides rows from them. Someone on a public link, signed in as no one, reads no row a `self` clause would
158
- choose. An app never reads past its owner's own access. A table's own `read_scope` governs opening the table directly.
159
- Working inside one row of a folder (`scope`) narrows the view, not who may read: a branch app shared with every manager
160
- still states the branch rule.
161
-
162
- ## 5 — A custom-code app
163
-
164
- ```
165
- lotics app create "<name>" --custom . # registers the app and links this directory (package.json#lotics)
166
- lotics app deploy -m "<what changed>" # build, upload, a new version live
167
- lotics app pull <app_id> # the live version's source, on a machine without the project or after another deploy
168
- ```
169
-
170
- The contract, and nothing more:
171
-
172
- - `@lotics/app-sdk` is React hooks and needs React 19 (`react` and `react-dom` `^19.2`); `react-router`
173
- (`^7` or `^8`) only for `@lotics/app-sdk/router`. Its reference is `node_modules/@lotics/app-sdk/AGENTS.md`.
174
- - `lotics app deploy` writes the app's declarations into `.lotics/` (`app_queries.d.ts` types
175
- `useQuery` by its aliases; include the directory in the project's TypeScript config), runs
176
- `npm run typecheck` when the project declares it, then `npm run build`, which must write a static
177
- `dist/` with an `index.html`. It uploads `dist/` and the source (without `node_modules`, `dist`,
178
- `.git`).
179
- - The app is a static bundle on the app host and reaches data only through the SDK.
180
-
181
- What the app reads and writes is bound on the app, never in the project: `lotics run
182
- set_app` binds named queries (`app_bindings`), `lotics run set_workflow` a workflow body, and each mints a
183
- version. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy uploads the build
184
- and carries every binding forward unchanged.
185
-
186
- **Named queries.** Author them as `kind: "project"` with a `filter`, naming each projected column
187
- (`{ "source": "amount", "output": "total" }`), so a row reads as `r.total`. Scope per-user reads with
188
- `is_current_member` **inside the query** — a member id passed from the client is chosen by the
189
- caller. Write one `description` per alias: it is the line a chat or MCP caller chooses by.
190
-
191
- **Workflows are the only way an app writes**, and every query and workflow bound to an app is also what
192
- an agent reads and runs there: `lotics docs agent_surface` § Declaring more states how each is shaped for
193
- that caller.
194
-
195
- ## 6 — Prove it, without a screen
196
-
197
- Static checks prove parse, types and names — they evaluate nothing. Rehearse a write first:
198
-
199
- ```
200
- lotics run set_workflow '{"source":"on({ type: \"app\", app_id: \"app_…\", alias: \"…\" });\n…","dry_run":true,"record_id":"rec_…"}'
201
- ```
202
-
203
- It walks the draft through the same engine an Act's preview uses, under the app's authority: reads are real,
204
- writes and sends are said and not made, and it returns what the run would answer plus the calls it would make.
205
- Pass `preview_inputs` for the values of a workflow that takes inputs and no row.
206
-
207
- Then run it end to end, on a throwaway record:
208
-
209
- ```
210
- lotics run run_app_query '{"app_id":"app_…","alias":"…","params":{…}}'
211
- lotics run run_app_workflow '{"app_id":"app_…","alias":"…","inputs":{…}}'
212
- # exits non-zero when the run failed, so it is assertable
213
- ```
214
-
215
- A workflow is also how an app **produces a document** — `generate_document` fills a template
216
- you registered once (`lotics docs document_templates`).
217
-
218
- ## 7 — Look at it, then name it
219
-
220
- Look at every app you apply, at a desktop width and at a phone's — every check above reads the
221
- definition, none of them the pixels — and judge each shot against the visual bar `design` opens on:
222
-
223
- ```
224
- lotics run screenshot_app '{"app_id":"app_…"}' -o ./shots
225
- # one PNG per width saved into ./shots, each with its text snapshot beside it as <name>.txt;
226
- # "path":"/rec_…" opens a screen inside the app
227
- ```
228
-
229
- From the CLI each image is a link signed for an hour, and `-o` saves it. Each shot is one screen, as a member sees it; `"screen":2` draws the next screen of
230
- the content scrolling inside the app, and so on to its end, and `"full_page":true` grows one image
231
- to the first five screens — one or the other. Beside each image comes its `snapshot`, the screen's
232
- accessibility tree as text — read it to check labels and values without opening the picture — and,
233
- where a table left columns off at that width, `shed` names them.
234
-
235
- The app is drawn live, as you, read-only: a screen that writes when it opens shows that write
236
- refused, and `errors` lists what failed on the page. A version that looks wrong is one
237
- `lotics app apply` away from the one before: apply the earlier tree again.
238
-
239
- For an app stated as a tree, `verdict` comes beside the images: what a check of that app finds now,
240
- beside its rows — what the next write would refuse it for and the notes
241
- on it. `verdict_unread` says why none was read.
242
-
243
- The app's `name`, `icon`, `color` and `description` are props of the App node; an app
244
- stating no `color` gets the platform's grey tile. `lotics run set_app` with the app's id and a `body` patch changes them
245
- on the app, and `lotics app pull` reads the tree back as the app holds it. The
246
- `description` heads the capability listing the member's chat agent reads on **every** turn, so a
247
- standing process the app expects that agent to carry out belongs there and nowhere else.
248
-
249
- **A caller outside the team gets its own app.** Sharing an app publicly, or giving an API key
250
- access to it, reaches every alias the app declares; no alias can be held back. So whatever
251
- outsiders may call is a SECOND app over the same tables: only the queries they may read and the
252
- workflows they may run. The desk the team works in stays a separate, private app. One only a server calls is an API app: `lotics docs app_bindings` § API apps.