@lotics/cli 0.321.125 → 0.321.126
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/dist/src/cli.js +97 -115
- package/dist/src/client.d.ts +2 -0
- package/docs/agent_surface.md +2 -1
- package/docs/app_architecture.md +3 -3
- package/docs/build.md +40 -32
- package/docs/cli_reference.md +2 -2
- package/docs/data_model.md +8 -1
- package/docs/design.md +91 -73
- package/docs/document_templates.md +13 -11
- package/docs/examples.md +429 -252
- package/docs/filters.md +2 -0
- package/docs/getting_started.md +3 -3
- package/docs/workflow_steps.md +2 -0
- package/docs/workflows.md +13 -9
- package/docs/working_in_a_workspace.md +1 -1
- package/package.json +3 -1
package/docs/filters.md
CHANGED
|
@@ -39,6 +39,8 @@ A condition may state these operators; each reads as the type's own below. Which
|
|
|
39
39
|
| `lt`, `lte`, `gt`, `gte` | number, date | below, at most, above, at least |
|
|
40
40
|
| `is_empty`, `is_not_empty` | every kind but yes/no | no value, or one |
|
|
41
41
|
|
|
42
|
+
A rollup that counts is 0 over no rows, never empty, and never negative: `lte 0` or `gt 0` says what blank or filled means, and an app's `where` entry `{ "empty": true | false }` on one is stored as that. A sum may be negative or add to 0 over rows: compare it with `== 0`.
|
|
43
|
+
|
|
42
44
|
`is` and `is_not` on a field that holds several options, members or records (a multi select, a many-link) are refused:
|
|
43
45
|
state `has_any_of`, `has_none_of` or `has_all_of`, which say whether the row must hold exactly them or just some.
|
|
44
46
|
A date is `"2026-10-15"` for that whole day, whatever time a value holds. An `is_any_of` or `is_none_of` on a number
|
package/docs/getting_started.md
CHANGED
|
@@ -6,9 +6,9 @@ Open the one page for the job. Pages are read with the `docs` tool (`docs path="
|
|
|
6
6
|
|
|
7
7
|
- **Build a workspace, or add an app:** `docs path="build"`. A bakery built call by call: tables with a check, the paper, the app, what the owner will ask an agent, the owner's rows, then pressing it.
|
|
8
8
|
- **Which apps a business needs, and who gets each:** `docs path="app_architecture"`.
|
|
9
|
-
- **Judge what you built:** `docs path="design/the-rubric"`.
|
|
9
|
+
- **Judge what you built:** `docs path="design/the-rubric"`. Each question answered by a call.
|
|
10
10
|
- **Change an app:** `docs path="reference/changing-an-app"`. `get_app`, then `set_app` with `nodes` and `base_version_id`. A table is changed with `get_table`, then `set_tables` with its `table_id` (`data_model`).
|
|
11
|
-
- **Enforce a rule on a table:** `docs path="workflows/table-checks"`. A condition no create, update or delete may meet, whoever makes it, and
|
|
11
|
+
- **Enforce a rule on a table:** `docs path="workflows/table-checks"`. A condition no create, update or delete may meet, whoever makes it, and its language.
|
|
12
12
|
- **Make a document:** `docs path="document_templates"`. A template, its slots and loops, and the act that files it on a record.
|
|
13
13
|
- **Enter data, count, answer a question:** `docs path="working_in_a_workspace"`. The right tool for each job; the value each field takes is `field_values`, choosing rows is `filters`.
|
|
14
14
|
- **Rows owed on a weekly pattern (a diary every weekday, a class every Tuesday):** `docs path="reference/cadence"` for a table's `records.cadence`; the Act that `makes` them is `reference/act-node`.
|
|
@@ -16,4 +16,4 @@ Open the one page for the job. Pages are read with the `docs` tool (`docs path="
|
|
|
16
16
|
- **Reach a connected service, or do what a button cannot:** `docs path="workflows"`. Triggers, steps and expressions; each service step is in `workflow_steps`.
|
|
17
17
|
- **Who can reach what, or why something was refused:** `docs path="permissions"`.
|
|
18
18
|
|
|
19
|
-
How each record is drawn is `design`;
|
|
19
|
+
How each record is drawn is `design`; a key's page in `reference` is read when a write or refusal names it; each screen in a complete workspace is `examples`.
|
package/docs/workflow_steps.md
CHANGED
|
@@ -1641,6 +1641,7 @@ above. A provider's refusal carries the provider's own words.
|
|
|
1641
1641
|
|
|
1642
1642
|
- Compute a formula over one record as its table's own formula fields compute: fields referenced as `{alias}`, lookups and rollups read as the row holds them.
|
|
1643
1643
|
- Writes nothing.
|
|
1644
|
+
- `values` (no link or files field) stand in for the row's stored cells, and formula fields reading them follow.
|
|
1644
1645
|
|
|
1645
1646
|
**Inputs**
|
|
1646
1647
|
|
|
@@ -1649,6 +1650,7 @@ above. A provider's refusal carries the provider's own words.
|
|
|
1649
1650
|
| `table_id` | string | yes | |
|
|
1650
1651
|
| `record_id` | string | yes | |
|
|
1651
1652
|
| `expression` | string | yes | |
|
|
1653
|
+
| `values` | object | | |
|
|
1652
1654
|
|
|
1653
1655
|
**Answer**
|
|
1654
1656
|
|
package/docs/workflows.md
CHANGED
|
@@ -174,8 +174,9 @@ A body names a table or document template by its alias (`query_records({ table_i
|
|
|
174
174
|
`sortBy(picks, "quantity")`, `rows[0].note`) and stored by key. A body that cannot be stored by key is refused at save,
|
|
175
175
|
naming the statement.
|
|
176
176
|
2. **An Act's own `workflow`** has the app's guards placed at the top of the body, between `<lotics:guards>` tags,
|
|
177
|
-
|
|
178
|
-
|
|
177
|
+
written again on every save: a save that leaves them out gets the app's again, at the top wherever the tags sat, and
|
|
178
|
+
one that changes a line between them is refused, so the act's row rule, `when`, `requires`, checks and locks always
|
|
179
|
+
run first. Your code goes on the lines after `</lotics:guards>`, above `<lotics:effects>` where one stands.
|
|
179
180
|
3. **A value is read as the record tools store it.** A single select reads as its option's alias and a member as its id;
|
|
180
181
|
an option is written by its alias wherever it meets a select — compared, listed, switched on, written — also beside a
|
|
181
182
|
name set from the field (`const s = record.status; s == "done"`) or in a list that search runs over
|
|
@@ -849,9 +850,8 @@ No step lists KiotViet's users: read `sold_by_id` off a row `kiotviet_list_invoi
|
|
|
849
850
|
## Table checks
|
|
850
851
|
|
|
851
852
|
A table check is one condition its table's record writes must not meet, declared beside the table's
|
|
852
|
-
`unique
|
|
853
|
-
|
|
854
|
-
surface makes it — a person, the API, the CLI, an agent, a workflow. A refusal writes nothing and
|
|
853
|
+
`unique`: a rule the owner gave. A deadline in `records.due` already marks its row late, so no check restates it. It is not a workflow: it reads the write and a few lookups and answers yes or no. It runs inside the write, on every create, update or delete it is `on`, whoever
|
|
854
|
+
makes it: a person, an agent or a workflow. A refusal writes nothing and
|
|
855
855
|
answers with the check's message, under its field when the check names one, and names the check.
|
|
856
856
|
|
|
857
857
|
A check is stated in its table's document, under `checks`, each under an alias of its own, and
|
|
@@ -883,12 +883,16 @@ alias (`record.status == "closed"`), and reads:
|
|
|
883
883
|
In a check a select reads as its one value (`record.kind == "retail"`), and a link (a one-row link too) and a lookup read as lists (`first(record.customer)`).
|
|
884
884
|
|
|
885
885
|
A check on several operations reads only what all of them carry, so one on creates and updates reads
|
|
886
|
-
neither `prev_record` nor `changes`.
|
|
886
|
+
neither `prev_record` nor `changes`. A check that reads `prev_record` therefore guards a move and never a
|
|
887
|
+
row made at the later option: what must hold of a row at a stage is a check on create and update over
|
|
888
|
+
`record` alone (`record.stage == "baking" && isNull(record.due_on)`).
|
|
887
889
|
|
|
888
890
|
A write that recomputes another table's rows (a rollup over lines, a lookup or a formula over a parent) judges each recomputed row as an update, by the checks `on` `update` that read a field the recompute changed; `changes` is what the recompute changed. A check that refuses on `changes` or on a status the row holds can therefore refuse the write that moved the parent, so it is gated on the field it means (`!isNull(changes.status)`).
|
|
889
891
|
|
|
892
|
+
A lookup that states no `limit` reads at most 50 rows, and `size` counts every row that matched; a function that reads every row of one (`sumBy`, `filter`, `join`) is refused at save, so the check states a `limit` (those rows are what it means) or uses a rollup. A sum over the rows that hang off one row (seats in a class) is a rollup on that row and a check on it: `{ "on": ["update"], "fail_when": "record.enrolled > record.seats", "message": "\"The class is full\"" }` over `enrolled`, a `count` rollup of the class's pupils.
|
|
893
|
+
|
|
890
894
|
A lookup reads with the access of the member who last saved the check, so saving one requires reading
|
|
891
|
-
every table its lookups read. A check's reads
|
|
895
|
+
every table its lookups read. A check's reads are locked, so two writes at the same moment can't both pass a check the other would fail. Values no two rows may share are the table's `unique`.
|
|
892
896
|
|
|
893
897
|
A `when`, a lookup or a `fail_when` that cannot decide — it fails, or the write's time runs out —
|
|
894
898
|
refuses the write, naming the part it was reading and, for an expression or a filter, what it met
|
|
@@ -1010,8 +1014,8 @@ automation or its table, and for an app's workflow the app's owner or an admin,
|
|
|
1010
1014
|
first when the run, or a run it retried, already wrote rows or called a service no delete reverses. An automation's or a
|
|
1011
1015
|
table workflow's retry runs in the background, as its runs do, and answers `queued`; a button's and an app's run while
|
|
1012
1016
|
the call waits. An app's call is checked again against the workflow's current inputs. A pruned run, a run of a workflow
|
|
1013
|
-
that is off, a reviewed act's run (call the act again)
|
|
1014
|
-
are not run again.
|
|
1017
|
+
that is off, a reviewed act's run (call the act again), a recording's filing (the recording retries its delivery) and
|
|
1018
|
+
a press through an outside link (its holder presses again) are not run again.
|
|
1015
1019
|
- **Stop.** `set_workflow_execution` with `action: "cancel"` stops a waiting run. Both answer
|
|
1016
1020
|
`execution_id`, `action`, `status`, `retry_of`, `error` and, for a retry, `original_wrote`: the rows and the irreversible
|
|
1017
1021
|
calls the first run wrote, which the retry makes again.
|
|
@@ -62,7 +62,7 @@ A long text not stored yet rides a file. `set_workflow` takes `source_file_id` i
|
|
|
62
62
|
|
|
63
63
|
Many rows come as a file. `query_records` with `as_file: true` lists no rows and sends them as a file: over MCP an embedded file (a whole set up to 12 MiB, a link past that), on the CLI a file `lotics run` saves where it runs (or in `-o <dir>`) and names. With `limit`, `offset`, `page_size`, `pagination` or `comments: true`, the file is that page as JSON, the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias. Without them it is every row the call matches, in its order, as JSON Lines: one row a line, each as `records` lists it. That file is also at `_file.url` for an hour and `_file.rows` counts its rows. `all: true` with `as_file` sends the same file; `all` alone lists every row in the answer instead, up to 1,000 rows (more is refused, naming `as_file`). A call matching no row answers `total: 0` and no file. One organization writes one such file at a time. A set too large to write within about 80 seconds is refused with how many rows were written; narrow it with `filters`, or name fewer fields with `field_keys`.
|
|
64
64
|
|
|
65
|
-
Many rows go back as a file too. `create_records` and `update_records` take `rows_file_id`: a JSON file holding the call's per-row keys, in place of stating them. Everything else stays in the call: `table_id`, `dry_run`, `row_op`, `return_fields`.
|
|
65
|
+
Many rows go back as a file too. `create_records` and `update_records` take `rows_file_id`: a JSON file holding the call's per-row keys, in place of stating them; for `create_records` the file may be the list of records itself. Everything else stays in the call: `table_id`, `dry_run`, `row_op`, `return_fields`.
|
|
66
66
|
|
|
67
67
|
```
|
|
68
68
|
{ "records": [{ "name": "Lan", "amount": 4000000 }, { "name": "Minh", "amount": 2500000 }] }
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lotics/cli",
|
|
3
|
-
"version": "0.321.
|
|
3
|
+
"version": "0.321.126",
|
|
4
4
|
"description": "Lotics SDK and CLI for AI agents",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -23,6 +23,8 @@
|
|
|
23
23
|
"generate:examples": "node --import tsx dev/examples_gen.ts",
|
|
24
24
|
"generate:snapshots": "node --import tsx dev/factory_snapshots.ts",
|
|
25
25
|
"generate:agent-surface": "node --import tsx dev/agent_surface_gen.ts",
|
|
26
|
+
"census:rebuild": "node --import tsx dev/rebuild_census.ts",
|
|
27
|
+
"export:workspace": "node --import tsx dev/export_workspace.ts",
|
|
26
28
|
"typecheck": "tsrs --noEmit",
|
|
27
29
|
"lint": "oxlint",
|
|
28
30
|
"test": "vitest run",
|