@lotics/cli 0.318.31 → 0.318.33
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/AGENTS.md +1 -1
- package/README.md +1 -1
- package/dist/src/cli.js +263 -274
- package/docs/agent_surface.md +9 -10
- package/docs/app_architecture.md +2 -2
- package/docs/app_bindings.md +25 -10
- package/docs/building_an_app.md +3 -3
- package/docs/cli_reference.md +3 -3
- package/docs/data_model.md +1 -1
- package/docs/design.md +194 -28
- package/docs/examples.md +39 -33
- package/docs/filters.md +3 -3
- package/docs/first_build.md +10 -20
- package/docs/getting_started.md +2 -2
- package/docs/migration.md +3 -2
- package/docs/workflow_steps.md +3 -76
- package/docs/workflows.md +137 -128
- package/package.json +1 -1
package/docs/agent_surface.md
CHANGED
|
@@ -31,9 +31,9 @@ app has.
|
|
|
31
31
|
|
|
32
32
|
| Called | What it says of itself | Takes | Generated for |
|
|
33
33
|
|---|---|---|---|
|
|
34
|
-
| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value — a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter — none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter — none over sources, none for a looked-up link or member, none for a number read in each row's own unit or currency | every entity the app draws; the filter params on the app's own entity alone |
|
|
35
|
-
| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list's; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register; none over sources, none for a Tab whose period reads a date holding a span |
|
|
36
|
-
| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals
|
|
34
|
+
| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value — a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter — none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter — none over sources, none for a looked-up link or member, none for a number read in each row's own unit or currency | every entity the app draws; the filter params on the app's own entity alone; a root List after the first over an entity, whose chips differ from the first's, adds one of its own, called by its key |
|
|
35
|
+
| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list's; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register, and of each later root List over an entity, called by its key; none over sources, none for a Tab whose period reads a date holding a span |
|
|
36
|
+
| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals`, and of each later root List over an entity, called by its key |
|
|
37
37
|
| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |
|
|
38
38
|
| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each List of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |
|
|
39
39
|
| `outside_<key>_one` | One row of <entity> by its id. | `record` | each Outside: the record a link opens, projected to the fields the Outside states |
|
|
@@ -78,7 +78,6 @@ the screen already holds.
|
|
|
78
78
|
| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |
|
|
79
79
|
| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. | | an app stating `scope` |
|
|
80
80
|
| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |
|
|
81
|
-
| `<rows>_measured_by_<link>` | The share of each <entity> row handed in its <rows> rows add, day by day. | `<entity>_ids` | a Reading stating `planned`, `done` and `measured` |
|
|
82
81
|
| `<entity>_sub_counts_by_<link>` | How many <entity> rows stand under each <entity> row handed in, through <link>, at each status. | `<entity>_ids` | a record's rows block over a hierarchy (`nests`), for the rows it draws |
|
|
83
82
|
| `<entity>_plan_places` | Every <place> the <entity> rows stand at, with what the plan draws of each. | | a register laid out as a `plan`: the places its rows stand at |
|
|
84
83
|
| `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |
|
|
@@ -117,7 +116,7 @@ run_app_query {"app_id":"app_…","alias":"order_list","params":{"status_is":"op
|
|
|
117
116
|
| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |
|
|
118
117
|
| `sort` | An order in place of the query's own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column's name |
|
|
119
118
|
| `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option's label, a member's name or a linked row's display; with `count_where` — a map of name → filter, never beside `count_by` — `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |
|
|
120
|
-
| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), or `day` (a date column, answered as `__day`),
|
|
119
|
+
| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), or `day` (a date column, answered as `__day`), `sum` (a number column, answered as `__sum`) and `avg` (a number column averaged over the group's rows that hold one, answered as `__avg`), each group with its `__count`. Sent with `params` and `filters` alone. Buckets are by day only: a period's total is one call per period, with `from` and `to` or a date filter |
|
|
121
120
|
| `limit`, `cursor` | A page — 200 rows at most, 50 where no `limit` is stated — and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |
|
|
122
121
|
| `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call's own |
|
|
123
122
|
|
|
@@ -286,8 +285,8 @@ Acts: every figure or list whose definition is the business's own (open orders,
|
|
|
286
285
|
It reads under the app's `rows` (every row, where the app states none of the table) and, on the app's own table, exactly the rows its list reads —
|
|
287
286
|
so never the table of an app whose List reads `sources`, several tables. A condition reading an
|
|
288
287
|
optional param narrows nothing when the call leaves it out; no param compares a number read in each row's
|
|
289
|
-
own unit or currency, or a date holding a span.
|
|
290
|
-
|
|
288
|
+
own unit or currency, or a date holding a span. A Query returns its `fields`; a caller counts, sums or
|
|
289
|
+
averages them with `run_app_query`'s `aggregate`. A Query, a Workflow and
|
|
291
290
|
a Reading's `key` take no name the app generates (`reference/app.generated-name`).
|
|
292
291
|
|
|
293
292
|
**A workflow** — a write no Act of the record makes, typed in the app's tree and its code set on the app:
|
|
@@ -305,9 +304,9 @@ a Reading's `key` take no name the app generates (`reference/app.generated-name`
|
|
|
305
304
|
}
|
|
306
305
|
```
|
|
307
306
|
|
|
308
|
-
`set_workflow` sets its code (`workflows`). A query
|
|
309
|
-
the tree
|
|
310
|
-
node, it is the tree's. A caller sees the description and
|
|
307
|
+
`set_workflow` sets its code (`workflows`). A query the app holds that
|
|
308
|
+
the tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,
|
|
309
|
+
whose answer notes it; declared as a Query node, it is the tree's. A caller sees the description and
|
|
311
310
|
each input's `description` and nothing else, so each says what the value is and what leaving it out means;
|
|
312
311
|
the check notes one that says nothing.
|
|
313
312
|
|
package/docs/app_architecture.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# App architecture — a worked split
|
|
2
2
|
|
|
3
|
-
The rule that splits a business into apps is in `first_build`, § 3: one app per main entity, and everything that belongs to a row on that row's page. This is one split it produces, settled before any tree is written
|
|
3
|
+
The rule that splits a business into apps is in `first_build`, § 3: one app per main entity, and everything that belongs to a row on that row's page. This is one split it produces, settled before any tree is written.
|
|
4
4
|
|
|
5
5
|
One bakery's wholesale arm, five people, seven apps:
|
|
6
6
|
|
|
@@ -38,4 +38,4 @@ record, one page. The owner reads the figures each register leads with. Each app
|
|
|
38
38
|
}
|
|
39
39
|
```
|
|
40
40
|
|
|
41
|
-
Then `set_access` gives each
|
|
41
|
+
Then `set_access` gives each app to all who work its rows (`first_build`, § 3). How each tree is composed is `design`.
|
package/docs/app_bindings.md
CHANGED
|
@@ -5,17 +5,29 @@ under an alias — a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):
|
|
|
5
5
|
|
|
6
6
|
| Binding | Declared with | The app calls it with | An agent calls it with |
|
|
7
7
|
|---|---|---|---|
|
|
8
|
-
| Query | `
|
|
8
|
+
| Query | `set_app`, a `Query` node | `useQuery("<alias>", params?)` | `run_app_query` |
|
|
9
9
|
| Workflow | `set_workflow` | `useWorkflow("<alias>")({ ...inputs })` | `run_app_workflow` |
|
|
10
10
|
|
|
11
11
|
Each runs under the app's authority (`{ type: "app", app_id }`), the app owner's reach — never the
|
|
12
12
|
calling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next
|
|
13
13
|
call uses it. `get_app` lists an app's aliases with their params and inputs.
|
|
14
14
|
|
|
15
|
-
Each reader returns a fingerprint of what it read
|
|
16
|
-
`
|
|
17
|
-
`
|
|
18
|
-
|
|
15
|
+
Each reader returns a fingerprint of what it read, and a write built on that read passes it back:
|
|
16
|
+
`get_workflow`'s `version` as `set_workflow`'s `expected_version`, and `get_app`'s version as `set_app`'s
|
|
17
|
+
`base_version_id`. The write is refused, and writes nothing, when it changed since; omit it for an unconditional write.
|
|
18
|
+
|
|
19
|
+
## API apps
|
|
20
|
+
|
|
21
|
+
An API app is one a customer's own server calls. It holds only `Query` and `Workflow` nodes, so no address serves it, and it cannot be shared publicly.
|
|
22
|
+
|
|
23
|
+
1. `set_app` with a tree of those nodes, naming the tables they read in `uses`. The answer carries the link where an admin creates its key, and `get_app` states it again.
|
|
24
|
+
2. `set_workflow` sets each workflow's code.
|
|
25
|
+
3. An admin opens the link and creates an app key (`lak_…`). It reaches this app alone and only calls it; no other route and no tool answers it, and that can never be widened. Its secret is shown once, so it goes straight into the server's secrets, and no tool creates or reads one.
|
|
26
|
+
4. To promise the shape to that server, an admin's `set_app` states `{ "app_id": "…", "api_published": true }`: a numbered contract and an OpenAPI document, and a later write that would break it is refused.
|
|
27
|
+
|
|
28
|
+
The server sends `Authorization: Bearer lak_…` to `POST /v1/apps/{app_id}/queries/{alias}` and `POST /v1/apps/{app_id}/workflows/{alias}/execute`. The answer holds what the app declares, with each row's own id and timestamps: no member's email, no field id, and a failed run a generic message beside its `execution_id`. A browser cannot call them, and a key never goes in a page.
|
|
29
|
+
|
|
30
|
+
A `Query` node reads one table or List with `rows` or `list`. A wider read states the whole query as `ast`, below.
|
|
19
31
|
|
|
20
32
|
## Queries
|
|
21
33
|
|
|
@@ -36,10 +48,13 @@ A save checks what a deploy checks: every table is in this workspace and within
|
|
|
36
48
|
every projected, filtered and sorted field resolves, every param token is declared, and a key a
|
|
37
49
|
node's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.
|
|
38
50
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
51
|
+
`set_app` states one as a `Query` node: `{ "type": "Query", "key": "<alias>", "ast": { … } }`, beside `params`,
|
|
52
|
+
`description` and `templates`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch
|
|
53
|
+
replaces its `ast`, `params` or `templates` whole. On an app that serves
|
|
54
|
+
code, `nodes` takes `{ "<alias>": { … } }` and merges each: send only the fields you change, `null` clears `params`,
|
|
55
|
+
`description` or `templates` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its
|
|
56
|
+
`children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by
|
|
57
|
+
name, and `get_app`'s `body` reads them back by alias.
|
|
43
58
|
|
|
44
59
|
### The query tree
|
|
45
60
|
|
|
@@ -105,7 +120,7 @@ name → `{ type, required?, description?, …per type }`. An entry is required
|
|
|
105
120
|
| `array` | `items` — one entry |
|
|
106
121
|
|
|
107
122
|
Nesting stops at depth 8. A `field`-form select tracks the field's options as they change; an
|
|
108
|
-
inline `options` set is a fixed list.
|
|
123
|
+
inline `options` set is a fixed list. A query's select param takes an option by alias, label or key, each condition reading it by its own field's options, and a value that is none of them is refused naming the options.
|
|
109
124
|
|
|
110
125
|
## Outputs
|
|
111
126
|
|
package/docs/building_an_app.md
CHANGED
|
@@ -154,7 +154,7 @@ people differ; a table with none is read whole by everyone the app is shared wit
|
|
|
154
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
155
|
|
|
156
156
|
A child read under a ruled row states its own rule, through its link to the parent; only a status history inherits.
|
|
157
|
-
|
|
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
158
|
choose. An app never reads past its owner's own access. A table's own `read_scope` governs opening the table directly.
|
|
159
159
|
Working inside one row of a folder (`scope`) narrows the view, not who may read: a branch app shared with every manager
|
|
160
160
|
still states the branch rule.
|
|
@@ -179,7 +179,7 @@ The contract, and nothing more:
|
|
|
179
179
|
- The app is a static bundle on the app host and reaches data only through the SDK.
|
|
180
180
|
|
|
181
181
|
What the app reads and writes is bound on the app, never in the project: `lotics run
|
|
182
|
-
|
|
182
|
+
set_app` binds named queries (`app_bindings`), `lotics run set_workflow` a workflow body, and each mints a
|
|
183
183
|
version. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy uploads the build
|
|
184
184
|
and carries every binding forward unchanged.
|
|
185
185
|
|
|
@@ -249,4 +249,4 @@ standing process the app expects that agent to carry out belongs there and nowhe
|
|
|
249
249
|
**A caller outside the team gets its own app.** Sharing an app publicly, or giving an API key
|
|
250
250
|
access to it, reaches every alias the app declares; no alias can be held back. So whatever
|
|
251
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.
|
|
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.
|
package/docs/cli_reference.md
CHANGED
|
@@ -28,7 +28,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
28
28
|
| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \| lotics run <tool> -`) — both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone — the error names both escapes. |
|
|
29
29
|
| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
|
|
30
30
|
| `lotics run <tool>` — **file cells** | A file in a tool's result carries its `fil_…` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file — this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |
|
|
31
|
-
| — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `
|
|
31
|
+
| — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `set_workflow`. A command exists only for work that touches a local file: `app apply`, `app create --custom`, `app pull`, `app deploy`. |
|
|
32
32
|
| — | **An app's queries and workflows take more than their params and inputs** (`lotics docs agent_surface`). `run_app_query '{"app_id","alias","params"}'` also takes `filters` and `sort` over the query's output columns, `fields` (the columns to return), `count` with `count_by` or `count_where`, `aggregate`, `limit` (200 rows at most; 50 where none is stated) and `cursor`, and `runs` — up to 20 reads in one call, each `{"alias", …}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {"key", …narrowing}` instead of the read arguments makes the file an app's Export makes (`lotics docs agent_surface`). `run_app_workflow '{"app_id","alias","inputs"}'` also takes `dry_run: true` — a rehearsal on the real inputs, nothing written or sent; the answer is what the run would return, with the reads it made under `dry_run.reads`, the calls it would make under `dry_run.writes` and the papers it rendered under `dry_run.papers` and the parts of the answer it could not say under `dry_run.unpredicted`; a workflow no dry run is offered of answers `status: "not_previewed"` — and `runs` — up to 50 runs in order, the first refused, failed or not previewed ending the call, an input `{"from_run": <index>, "path": "data.<key>"}` reading an earlier run's answer. |
|
|
33
33
|
| — | **The exit code reports the WORK, not just the call — for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` — a dry run asked for and not given) exit non-zero and print `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |
|
|
34
34
|
| `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries — an object with a `url`, a `filename` and the `expires_at` its signature ends at, at any depth, such as `screenshot_app`'s images. Each is fetched into `<dir>` (created if missing) under its `filename`, taking a free spelling beside a file of that name already there, and a link's `snapshot` text is written beside it as `<name>.txt`. The written paths follow the answer on **stdout**, one per line (on stderr under `--json`, whose stdout stays the one object). A link is signed for an hour; one the store no longer serves exits non-zero. A workspace file states no `expires_at` and is left to `lotics file download`. |
|
|
@@ -47,8 +47,8 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
47
47
|
| `lotics knowledge rm <id...>` | Delete docs via `set_knowledge` (`{ knowledge_doc_id, delete: true }`), one call per id: each must be a live doc you manage that no app or workflow names, and the command reports which succeeded and which failed. Sharing and history are kept. The REST execute path does not gate `needsApproval`, so this runs unattended. |
|
|
48
48
|
| `lotics knowledge restore <id...>` | Bring deleted docs back via `set_knowledge` (`{ knowledge_doc_id, restore: true }`), one call per id: each must be a deleted doc you manage, and the command reports which succeeded and which failed. Refuses the no-argument form. |
|
|
49
49
|
| `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`) and links `[path]` (default `./<name>`, made when absent) to it by writing `package.json#lotics` (the app and its workspace, which is how `app deploy` in that directory finds both) — into the project's own `package.json` when it has one, every other key kept, otherwise a `package.json` holding the link alone. Nothing else is written and nothing is installed: the project is yours. `app deploy` needs `@lotics/app-sdk` (React 19) and an `npm run build` that writes a static `dist/` with an `index.html`. A directory already linked to an app is refused before the app row exists. The app has no version until the first `lotics app deploy`. `--custom` is required: a JSON app is made by `lotics app apply` (the tool `set_app`). The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` once the project installs it. |
|
|
50
|
-
| `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (
|
|
51
|
-
| `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour)
|
|
50
|
+
| `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (its identity and Query nodes) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ "app_id": "…", "version_id": "…", "digest": "…" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) — a custom-code project records both in `package.json#lotics`, a single file has no such place — so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |
|
|
51
|
+
| `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version — its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) — what would refuse the tree, and what it would grant and remove — and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |
|
|
52
52
|
| `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`GET /v1/apps/{id}/types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent; a type error in the app's own files stops the deploy, one inside an installed package is reported and does not) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged — those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |
|
|
53
53
|
| `lotics docs` \| `lotics docs <area>[/<section>]` \| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** — the model reference, this index, and every doc under `docs/` — so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal — a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`; a literal search that finds nothing while the pattern read as an expression matches (`a|b`) returns those lines under a note saying so, and `--literal` keeps the literal zero; with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` — the dialect the knowledge lines of `get_workspace` with `search` are read in — each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |
|
|
54
54
|
| `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
|
package/docs/data_model.md
CHANGED
|
@@ -55,7 +55,7 @@ express rather than quietly picking the nearest value.
|
|
|
55
55
|
|
|
56
56
|
A value read through a link or a lookup reads exactly as the same field would on its own row: an option written by its alias in
|
|
57
57
|
a body and read as its key, a member or a link by its id. A value a check matches
|
|
58
|
-
across tables is a link to one table: two selects never compare, and a save that compares them is refused.
|
|
58
|
+
across tables is a link to one table: two selects never compare, and a save that compares them is refused, in a check's lookup too. A filter or a write on another table's select takes a value read from this one by its alias, else its label.
|
|
59
59
|
|
|
60
60
|
A lookup reads as one flat list of the values it looks up, in a check and in every body: `first(record.x)` is the one value through a one-row link and `includes(record.x, v)` asks whether any row holds `v`; two selects never compare, so a value matched across tables is a link to one table. A single member, a single select, a number or a text reads as the value itself, and `first(...)` of one is refused when the body is saved. A rollup that adds up (a sum, a count) over no rows is 0, never empty, as `sum` over an empty list is; a min, a max or an average over no rows is empty.
|
|
61
61
|
|
package/docs/design.md
CHANGED
|
@@ -5,8 +5,7 @@ tree states COMPOSITION — which fields, lists and acts each job's screen holds
|
|
|
5
5
|
one way per concept. A node the tree leaves out draws its default, from the table's facts (`records`, the stage, the
|
|
6
6
|
write rules): a List's Readings band, the stage buttons, the picture, a Record's Sections. State a node to change it,
|
|
7
7
|
or `false` at it to turn it off (`"readings": false`, a Record's `"row": { "image": false }`). A drawn Field is a control unless it
|
|
8
|
-
or its entity is read-only (`edit: false`); a stepped status never is, since Acts move it.
|
|
9
|
-
worked in a whole workspace is `examples/<treatment>`, and which apps a business needs is `first_build`, § 3.
|
|
8
|
+
or its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Which apps a business needs is `first_build`, § 3.
|
|
10
9
|
|
|
11
10
|
**The visual bar.** Every screen is judged against it; a miss is a change to the tree.
|
|
12
11
|
|
|
@@ -16,8 +15,9 @@ worked in a whole workspace is `examples/<treatment>`, and which apps a business
|
|
|
16
15
|
- What needs attention leads the row: `records.mark` on a select or a computed category (a formula stating its options;
|
|
17
16
|
where it is empty, its seat is blank). A yes that needs attention (papers still owed) is a `Check` of its List over a
|
|
18
17
|
yes/no formula, in the warning tone on the row's line; every other yes reads in the success tone.
|
|
19
|
-
- A list's columns: the name and its lead, the status, then the
|
|
20
|
-
fact once:
|
|
18
|
+
- A list's columns: the name and its lead, the status, then the columns the job reads on every row, as many as fit a desk. Each
|
|
19
|
+
fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields
|
|
20
|
+
the row's name to the subtitle's first part and stands first on its line.
|
|
21
21
|
- A list worked by a date states `sort` on that date's column, newest first; without one, a register reads newest made
|
|
22
22
|
first and a record's child List in the order its rows were added.
|
|
23
23
|
- Someone is a face wherever they are read: a link to a table stating `records.party` draws its row's face; a member
|
|
@@ -30,13 +30,172 @@ worked in a whole workspace is `examples/<treatment>`, and which apps a business
|
|
|
30
30
|
means something.
|
|
31
31
|
- Every app states its tile's `color`, apart from the workspace's other apps where it can be.
|
|
32
32
|
- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the
|
|
33
|
-
carrier, the authority) in the Section where that work happens,
|
|
33
|
+
carrier, the authority) in the Section where that work happens, and the source of a
|
|
34
34
|
figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere.
|
|
35
35
|
|
|
36
36
|
**Each shot answers:** can the person find their row? Is what needs doing first, on the row's lead? Is anything
|
|
37
37
|
repeated or empty? Is anyone shown without their face? Is every paper visible? Across the workspace: can each app be
|
|
38
38
|
told apart by its own screen, and does any app hold a second entity behind tabs? A failed answer is a change to the tree.
|
|
39
39
|
|
|
40
|
+
<!-- generated:start words -->
|
|
41
|
+
|
|
42
|
+
**The words most builds state.** A node's page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.
|
|
43
|
+
|
|
44
|
+
**Table**
|
|
45
|
+
|
|
46
|
+
- `ref` (alias): A created table's handle in this call
|
|
47
|
+
- `label` (text, required): The table's name in the workspace
|
|
48
|
+
- `singular` (text): One row of this table, in the business's own words
|
|
49
|
+
- `title` (alias): The alias of the field that names a row wherever a link or a record shows one
|
|
50
|
+
- `fields` (map of alias → Field, required): The table's columns, each under its alias, which is its key here and so is never stated inside it
|
|
51
|
+
- `records` (any value): How a row is recognised
|
|
52
|
+
- `checks` (map of alias → table check (`workflows/table-checks`)): The conditions a write of the table's rows may not meet, each under its alias
|
|
53
|
+
- `unique` (list (at least one) of list of alias (at least one)): Sets of fields whose values no two live rows share
|
|
54
|
+
|
|
55
|
+
**Any field**
|
|
56
|
+
|
|
57
|
+
- `label` (text, required): The field's name in the workspace
|
|
58
|
+
- `required` (boolean): Refuse a record whose cell for this field is empty
|
|
59
|
+
- `default_from` (text): Copied when a record is made off the row a one-row link of this entity names
|
|
60
|
+
|
|
61
|
+
**`number` field**
|
|
62
|
+
|
|
63
|
+
- `notation` (notation): How the figure reads
|
|
64
|
+
- `min` (number | text): Refuse a create or update whose value is below this
|
|
65
|
+
|
|
66
|
+
**`select` field**
|
|
67
|
+
|
|
68
|
+
- `options` (list of Select option (at least one), required): The choices, in the order every picker and every ladder lists them
|
|
69
|
+
- `multi` (boolean): Allow multiple selections
|
|
70
|
+
|
|
71
|
+
**`link` field**
|
|
72
|
+
|
|
73
|
+
- `table` (text, required): The table the link points at
|
|
74
|
+
- `multi` (boolean, required): Whether a row links to one row or many
|
|
75
|
+
- `pair` (`true` | alias): Makes the link two-way
|
|
76
|
+
|
|
77
|
+
**`formula` field**
|
|
78
|
+
|
|
79
|
+
- `expression` (text, required): The expression, over fields of THIS entity by alias in braces
|
|
80
|
+
- `output_type` (`"number"` | `"text"` | `"date"` | `"datetime"` | `"boolean"` | `"select"`): Holds a formula to the type its readers need
|
|
81
|
+
|
|
82
|
+
**`rollup` field**
|
|
83
|
+
|
|
84
|
+
- `via` (alias, required): The alias of a link of this table to roll up from
|
|
85
|
+
- `op` (operation, required): The operation over the linked rows
|
|
86
|
+
- `field` (alias): The alias of the field on the linked table the operation reads
|
|
87
|
+
|
|
88
|
+
**`lookup` field**
|
|
89
|
+
|
|
90
|
+
- `via` (alias, required): The alias of a link of this table to look up through
|
|
91
|
+
- `field` (alias, required): The alias of the field on the linked table to show
|
|
92
|
+
|
|
93
|
+
**`autonumber` field**
|
|
94
|
+
|
|
95
|
+
- `prefix` (text): Literal prefix prepended to every display value (e.g. 'KH-' → 'KH-001')
|
|
96
|
+
|
|
97
|
+
**`records`**
|
|
98
|
+
|
|
99
|
+
- `subtitle` (list of alias (1–2)): Up to two fields read under the title wherever a row is drawn (a code, a date, a party)
|
|
100
|
+
- `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)
|
|
101
|
+
- `status` (Status): The stage a row moves through, a single select, drawn in the record's head, or its Side where the Side states it
|
|
102
|
+
- `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)
|
|
103
|
+
- `image` (alias): A files field that pictures the row
|
|
104
|
+
- `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)
|
|
105
|
+
- `limits` (map of alias → (alias | number)): A number read against a bound
|
|
106
|
+
- `starts` (map of alias → `"today"` | `"me"`): What a field of a row being added starts at, where that start is certain
|
|
107
|
+
- `mark` (alias): A single select (or a lookup of one through a one-row link), or a formula that states its options, whose option leads the row wherever a mark leads it
|
|
108
|
+
- `settled` (alias): A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines
|
|
109
|
+
|
|
110
|
+
**`records.status`**
|
|
111
|
+
|
|
112
|
+
- `field` (alias, required): The single select that is the row's state, its options in the order the work goes through them, read as steps by itself on a record whose parts state no `at`
|
|
113
|
+
- `closed` (list of alias (at least one)): Options that end the work
|
|
114
|
+
- `history` (text): A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who)
|
|
115
|
+
- `dates` (map of alias → alias): Option alias → a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it
|
|
116
|
+
- `stages` (map of alias → Stage): Option alias → who owns that stage and how long it should take
|
|
117
|
+
|
|
118
|
+
**App**
|
|
119
|
+
|
|
120
|
+
- `key` (alias, required): The app's alias, its name among apps
|
|
121
|
+
- `name` (text, required): The job, in the words of the people who do it
|
|
122
|
+
- `children` (list of (List | Sheet | Query | Workflow) (at least one)): The App's Views in order
|
|
123
|
+
- `color` (colour): The launcher tile's colour
|
|
124
|
+
- `pages` (list of Record (at least one)): The page the rows of an entity open, one per entity, each a Record stating its `entity`
|
|
125
|
+
|
|
126
|
+
**List**
|
|
127
|
+
|
|
128
|
+
- `entity` (alias, required): The table whose rows the List draws
|
|
129
|
+
- `create` (boolean | list of alias (at least one)): The fields an add asks
|
|
130
|
+
- `columns` (list of (alias | Edit column)): Fields read after the row's title
|
|
131
|
+
- `label` (text): The register's name in the app's lists and tab strip
|
|
132
|
+
- `filters` (list of (alias | Tiered filter) (at most 3)): Fields the reader narrows by every day, beside the stage chips
|
|
133
|
+
- `children` (list of (Tab | Reading | Export | Act | List) (at least one)): Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view
|
|
134
|
+
- `key` (alias): Names the List among its siblings and in a Query's `list`
|
|
135
|
+
- `sort` (Sort key | list of Sort key (at least one)): The rows' order
|
|
136
|
+
- `layout` (layout): A word, or an object stating one layout with its data
|
|
137
|
+
- `remove` (boolean): Rows offer a Delete
|
|
138
|
+
- `search` (list of alias (at least one)): Fields the search box reads
|
|
139
|
+
- `where` (narrowing): A fixed narrowing on the server, for every reader
|
|
140
|
+
- `group` (alias): A field the rows stand grouped by
|
|
141
|
+
- `expect` (alias | Expect): What a record should hold, shown before it does
|
|
142
|
+
- `opens` (narrowing): The view the register opens on, a chip the reader may take away
|
|
143
|
+
|
|
144
|
+
**Record**
|
|
145
|
+
|
|
146
|
+
- `entity` (alias, required): The table whose rows open on this page
|
|
147
|
+
- `children` (list of (alias | Field | Fieldset | Section | Side | Outside | List | Reading | Statement | Act | Check) (at least one)): Parts (Section, Side), or for a one-part record its Fields, Fieldsets, Lists, Readings and Statements directly
|
|
148
|
+
- `add` (`false` | list of alias (at least one)): What a new row asks where a picker of this entity offers one, anywhere in the App
|
|
149
|
+
- `row` (Record row): How the App reads this entity's rows wherever it lists them
|
|
150
|
+
- `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer
|
|
151
|
+
|
|
152
|
+
**Section**
|
|
153
|
+
|
|
154
|
+
- `title` (text, required): The part's heading
|
|
155
|
+
- `key` (alias): Unique among its siblings
|
|
156
|
+
- `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act) (at least one)): What the part draws, in reading order
|
|
157
|
+
- `at` (list of alias (at least one)): Options of the record's status during which this part is the work now
|
|
158
|
+
- `when` (condition): Drawn only while this holds
|
|
159
|
+
|
|
160
|
+
**Field**
|
|
161
|
+
|
|
162
|
+
- `field` (alias, required): The field's alias
|
|
163
|
+
- `edit` (boolean): Shows a value nobody changes here
|
|
164
|
+
- `label` (text): The heading of the field's gallery or prose block, where it draws as one
|
|
165
|
+
- `block` (boolean): Gives a field room of its own
|
|
166
|
+
|
|
167
|
+
**Act**
|
|
168
|
+
|
|
169
|
+
- `key` (alias, required): The act's name
|
|
170
|
+
- `label` (text, required): The verb, as the reader says it
|
|
171
|
+
- `when` (condition): The act works only while this holds
|
|
172
|
+
- `set` (map of alias → value): What the act writes
|
|
173
|
+
- `asks` (list of (alias | `{ "field": alias, "starts": "today" | "me" }` | Asked input) (at least one)): What the reader states on pressing
|
|
174
|
+
- `confirm` (`true` | text): The press asks first
|
|
175
|
+
- `requires` (list of alias (at least one)): Fields filled first, each drawn where the act stands
|
|
176
|
+
- `template` (alias): A document template it makes a file from
|
|
177
|
+
- `into` (alias): The record's files field keeping the document
|
|
178
|
+
- `owner` (`"field"` | `"link.field"` | `{ "group": id }`): Who presses it
|
|
179
|
+
- `workflow` (alias): The workflow it runs for what `set` cannot say
|
|
180
|
+
- `danger` (`true`): The act destroys or cannot be undone
|
|
181
|
+
|
|
182
|
+
**Check**
|
|
183
|
+
|
|
184
|
+
- `field` (alias, required): A yes/no or text formula of the page's entity
|
|
185
|
+
- `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing check refuses
|
|
186
|
+
- `resolve` (alias): An Act on one row of this entity that clears it
|
|
187
|
+
|
|
188
|
+
**Reading**
|
|
189
|
+
|
|
190
|
+
- `label` (text): What the figure is called
|
|
191
|
+
- `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one
|
|
192
|
+
- `by` (alias | Tiered filter): Splits the rows into parts
|
|
193
|
+
- `where` (narrowing): Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date's `{ "now": true }` is read when the rows are), whose field is `{ "empty": true | false }`, or whose member field holds the reader (`{ "me": true }`)
|
|
194
|
+
- `entity` (alias): The List's rows
|
|
195
|
+
- `over` (alias): The date that places a row in time
|
|
196
|
+
|
|
197
|
+
<!-- generated:end words -->
|
|
198
|
+
|
|
40
199
|
## Look at it
|
|
41
200
|
|
|
42
201
|
After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` (`screen`
|
|
@@ -51,39 +210,39 @@ send the tree saved before the change as `body` with `app_id`, nulling an App pr
|
|
|
51
210
|
A treatment named below is one the answer of `set_app` notes when the rows call for it and nothing draws it, naming the
|
|
52
211
|
node that would state it; a note refuses nothing. Each kind of row's view is chosen before its List is written:
|
|
53
212
|
|
|
54
|
-
| The rows are | The treatment | Its
|
|
213
|
+
| The rows are | The treatment | Its own page |
|
|
55
214
|
|---|---|---|
|
|
56
|
-
| People or organisations | `records.party`, with a photo or logo as its `image` |
|
|
57
|
-
| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/
|
|
215
|
+
| People or organisations | `records.party`, with a photo or logo as its `image` | |
|
|
216
|
+
| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |
|
|
58
217
|
| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
|
|
59
|
-
| Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column |
|
|
218
|
+
| Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | |
|
|
60
219
|
| Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` | `reference/lanes`, `reference/write-rules` |
|
|
61
220
|
| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |
|
|
62
|
-
| Opened to be worked on | the Record's Sections, in the order the work reaches them — `at` where it moves in steps; fields only one kind of row holds (a delay's cause, a safety issue's hours lost) in a Section whose `when` names that kind |
|
|
63
|
-
| Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes; a List with `same` where read-only |
|
|
221
|
+
| Opened to be worked on | the Record's Sections, in the order the work reaches them — `at` where it moves in steps; fields only one kind of row holds (a delay's cause, a safety issue's hours lost) in a Section whose `when` names that kind | |
|
|
222
|
+
| Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes; a List with `same` where read-only | |
|
|
64
223
|
| A related row's value on the list (the newest contract's end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |
|
|
65
|
-
| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings |
|
|
66
|
-
| Counted over a period | the register's Tabs over one `period`; a Tab's `totals` for a child's sums before, during and through it; an open Tab's `where` reads only what was true at the period's end, never a status the row moves on from |
|
|
67
|
-
| Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` |
|
|
224
|
+
| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | |
|
|
225
|
+
| Counted over a period | the register's Tabs over one `period`; a Tab's `totals` for a child's sums before, during and through it; an open Tab's `where` reads only what was true at the period's end, never a status the row moves on from | |
|
|
226
|
+
| Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | |
|
|
68
227
|
| A plan of spans | List `layout: {"gantt": {"start": …}}` | `reference/gantt` |
|
|
69
228
|
| Stood at a place on a plan, flat or in 3D — pallets, bins | List `layout: {"plan": …}`; places state `plan_place` | `reference/plan` |
|
|
70
|
-
| Checked item by item against a standard | a List with `checklist: {"photo": …, "clause": …, "failed": […], "passed": …}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names — a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard's items, each item is a line marked the same way and filled by the block's columns |
|
|
71
|
-
| A place before and after the work | a List with `compare: {"before": …, "after": …}`: two files fields read side by side, or two value fields read as one struck-then-new column |
|
|
229
|
+
| Checked item by item against a standard | a List with `checklist: {"photo": …, "clause": …, "failed": […], "passed": …}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names — a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard's items, each item is a line marked the same way and filled by the block's columns | |
|
|
230
|
+
| A place before and after the work | a List with `compare: {"before": …, "after": …}`: two files fields read side by side, or two value fields read as one struck-then-new column | |
|
|
72
231
|
| Spots on a drawing | `records.pin: {"on": …, "x": …, "y": …}` on the spots' table: a record listing rows that link to them draws the picture with a numbered pin at each; the picture is the `on` row's `records.image` | `reference/record-places-pins-and-cadence` |
|
|
73
232
|
| Photos that must be taken on site | `records.on_site: {"photos": […]}`: a photo taken through the camera keeps where the device stood, and a record holding one taken away says so | `reference/record-places-pins-and-cadence` |
|
|
74
233
|
| The real size of the thing (a carton, a piece of furniture, a pallet) | `records.size: {"across": …, "along": …, "up": …}`: three number fields in one length unit, read as one fact "400 × 300 × 250 mm" after the subtitle; a plan register draws each box at that size | `reference/record-places-pins-and-cadence`, `reference/plan` |
|
|
75
234
|
| A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |
|
|
76
235
|
| Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |
|
|
77
|
-
| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record's `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` — a link a member makes of the record, never a seat; the link's page names the record only where the Outside states its title's field |
|
|
78
|
-
| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them |
|
|
79
|
-
| A record's own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (
|
|
236
|
+
| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record's `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` — a link a member makes of the record, never a seat; the link's page names the record only where the Outside states its title's field | |
|
|
237
|
+
| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |
|
|
238
|
+
| A record's own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |
|
|
80
239
|
| Rows that are each a place a record is sent | a List with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `reference/publish-desk` |
|
|
81
|
-
| Papers an agent reads, where the owner asked for one | an Act's `intake` with `fills` |
|
|
82
|
-
| Calls and visits | an Act's `record` |
|
|
83
|
-
| Changes a workflow proposes that a person approves row by row — a price list applied, a statement matched to what is owed | an Act's `workflow` with `review`, its body returning a changeset in `data.review` |
|
|
84
|
-
| Documents covering lines | a List with `under` |
|
|
85
|
-
| Rows on file a record takes in | a List with `pick` |
|
|
86
|
-
| One owner's question across jobs | an App of Tabs and Readings and no register |
|
|
240
|
+
| Papers an agent reads, where the owner asked for one | an Act's `intake` with `fills` | |
|
|
241
|
+
| Calls and visits | an Act's `record` | |
|
|
242
|
+
| Changes a workflow proposes that a person approves row by row — a price list applied, a statement matched to what is owed | an Act's `workflow` with `review`, its body returning a changeset in `data.review` | |
|
|
243
|
+
| Documents covering lines | a List with `under` | |
|
|
244
|
+
| Rows on file a record takes in | a List with `pick` | |
|
|
245
|
+
| One owner's question across jobs | an App of Tabs and Readings and no register | |
|
|
87
246
|
|
|
88
247
|
What these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `building_an_app`), never a new node.
|
|
89
248
|
|
|
@@ -94,7 +253,8 @@ What these nodes do not state, a long-form writing page or a bespoke tool, is a
|
|
|
94
253
|
`records.party` is `"person"` where the rows are people (a contact, a patient, a driver) and
|
|
95
254
|
`"organization"` where they are companies (a customer, a supplier, a carrier). Every surface drawing one of
|
|
96
255
|
its rows then draws a face: its `image` (a photo, a logo), else its initials. Without it, a person is drawn as a thing. A workspace
|
|
97
|
-
member is a `member` field, and is drawn by their face already.
|
|
256
|
+
member is a `member` field, and is drawn by their face already. A column holding a link to several rows of people,
|
|
257
|
+
or several members, draws their faces as a stack that names them on hover. Worked: `examples/party`.
|
|
98
258
|
|
|
99
259
|
#### Image
|
|
100
260
|
|
|
@@ -195,7 +355,7 @@ register; a register whose job is a strict order, a first-come queue, states `at
|
|
|
195
355
|
Who changed what and when is the platform's audit trail, never a table and never shown by an app. When a stage's moment matters
|
|
196
356
|
to the business — reported, filtered, printed — it is a date on the row that `records.status.dates` stamps as the row
|
|
197
357
|
enters the option, whoever writes: the one way a status is timed, and the moment a stage's `within` runs from (each stage, and
|
|
198
|
-
each open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated; a move whose
|
|
358
|
+
each open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a record whose parts state no `at` draws it as steps by itself: no date fields or formulas copy it); a move whose
|
|
199
359
|
day may already be past `asks` that date with `starts: "today"`. `records.status.history` names a child the record write path appends one row to per
|
|
200
360
|
status move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves
|
|
201
361
|
per person, or time in a stage a row re-enters. An event with facts of its own — a reason, an amount, a signature — is
|
|
@@ -206,7 +366,7 @@ stage is signed once per person, read off who moved the row.
|
|
|
206
366
|
|
|
207
367
|
A List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job's headline number —
|
|
208
368
|
its exception as a formula's yes/no in a Reading's `where` (what is short), never a stage the
|
|
209
|
-
status chips already count, nor the overdue rows the register's summary line counts from `records.due` — then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted
|
|
369
|
+
status chips already count, nor the overdue rows the register's summary line counts from `records.due` — then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows. A register with no such figure and no single select to split by gets no default band.
|
|
210
370
|
A grid (`by` and `across`) reads on a Sheet. A Sheet — a View of Readings at the App's root, beside its Lists or alone —
|
|
211
371
|
answers one owner's question across jobs, each Reading windowed by the reader's period (the App's `period`), and a
|
|
212
372
|
List on it hands over the rows to act on. Many Readings stand on several Sheets, each a View the reader picks. A
|
|
@@ -234,6 +394,12 @@ an app (`first_build` § 3).
|
|
|
234
394
|
|
|
235
395
|
#### Sections
|
|
236
396
|
|
|
397
|
+
A record is a head, its parts and at most one Side. From three parts it shows one part at a time; fewer stack. State each
|
|
398
|
+
part whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it
|
|
399
|
+
unstated. A step may hold nothing but its name. What a person needs in view at every part (who it is for, how to reach
|
|
400
|
+
them) goes in a Side: it leaves the head and stays on the rows. The status stands in the head or the Side, never a
|
|
401
|
+
Section. `row` changes how the app's rows read, never a page.
|
|
402
|
+
|
|
237
403
|
The Record's Sections, in the order the work reaches them: the fields people write, a Field per paper the record
|
|
238
404
|
keeps, a child List per child, the Acts at each one's foot. A register's `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record's, and a figure that is final only from a stage is a Field of that stage's Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the
|
|
239
405
|
default record: every field a person writes. Behaviour belongs in an Act.
|