@lotics/cli 0.318.24 → 0.318.26
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 +188 -168
- package/dist/src/client.js +1 -1
- package/docs/agent_surface.md +19 -20
- package/docs/app_architecture.md +5 -5
- package/docs/building_an_app.md +1 -1
- package/docs/cli_reference.md +2 -2
- package/docs/design.md +27 -47
- package/docs/examples.md +180 -212
- package/docs/first_build.md +46 -45
- package/docs/workflows.md +10 -5
- package/docs/working_in_a_workspace.md +1 -1
- package/package.json +1 -1
package/docs/first_build.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
# First build — a whole workspace, call by call
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The worked business: a bakery takes cake orders at the counter, a customer and one line per cake from the menu, moving taken, baking, ready, collected, with a slip printed when ready.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 0. Ask once
|
|
6
|
+
|
|
7
|
+
`get_workspace` shows what already exists. Before the first write, ask the owner once, in one message, only what you cannot settle yourself: their papers and lists (a photo, a spreadsheet, a file), anything written about how it should work, what each person needs to see first, and what no paper tells you that would change the tables or who does which step. One sentence per question, nothing else in the message. The owner answers by hand, so every question costs them time: ask nothing they gave or a paper settles. Never ask about stages or design: take a default and list it in your report. Wait for the answer. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
|
|
6
8
|
|
|
7
9
|
## 1. Tables and their checks: `set_tables`
|
|
8
10
|
|
|
9
|
-
One call, linked tables together
|
|
11
|
+
One call, linked tables together. A new table is named by its `ref`, which becomes its alias. One table per kind of thing, one column per fact, a link wherever one record points at another. A status is the stage of the work, six options or fewer; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. A table people work states `title` (who or what a row is; a code only where nothing else names it), `records` (an app over a table without it is refused) and `singular` (so is an Add over a table lacking it).
|
|
10
12
|
|
|
11
13
|
```json
|
|
12
14
|
{
|
|
@@ -20,23 +22,21 @@ One call, linked tables together; a call names a table by its alias, a new table
|
|
|
20
22
|
"ref": "menu_item", "label": "Menu", "singular": "Menu item", "title": "name",
|
|
21
23
|
"fields": {
|
|
22
24
|
"name": {"type": "text", "label": "Cake", "required": true},
|
|
23
|
-
"photo": {"type": "files", "label": "Photo"},
|
|
24
25
|
"price": {"type": "number", "label": "Price", "required": true, "notation": {"style": "currency", "currency": "USD"}}
|
|
25
26
|
},
|
|
26
|
-
"records": {"figure": "price"
|
|
27
|
+
"records": {"figure": "price"}
|
|
27
28
|
},
|
|
28
29
|
{
|
|
29
30
|
"ref": "cake_order", "label": "Cake orders", "singular": "Cake order", "title": "reference",
|
|
30
31
|
"fields": {
|
|
31
|
-
"reference": {"type": "autonumber", "label": "Number", "prefix": "CK-"
|
|
32
|
+
"reference": {"type": "autonumber", "label": "Number", "prefix": "CK-"},
|
|
32
33
|
"customer": {"type": "link", "label": "Customer", "table": "customer", "multi": false, "required": true},
|
|
33
34
|
"due_on": {"type": "date", "label": "Pickup on"},
|
|
34
35
|
"pay_by": {"type": "date", "label": "Pay balance by"},
|
|
35
36
|
"lines": {"type": "link", "label": "Cakes", "table": "cake_line", "multi": true, "pair": "order"},
|
|
36
37
|
"total": {"type": "rollup", "label": "Total", "via": "lines", "op": "sum", "field": "amount"},
|
|
37
38
|
"prepaid": {"type": "number", "label": "Prepaid", "notation": {"style": "currency", "currency": "USD"}},
|
|
38
|
-
"
|
|
39
|
-
"paid": {"type": "formula", "label": "Paid", "expression": "{total} > 0 && {balance} <= 0", "output_type": "boolean"},
|
|
39
|
+
"paid": {"type": "formula", "label": "Paid", "expression": "{total} > 0 && {prepaid} >= {total}", "output_type": "boolean"},
|
|
40
40
|
"slip": {"type": "files", "label": "Slip"},
|
|
41
41
|
"stage": {"type": "select", "label": "Stage", "default": ["taken"], "options": [
|
|
42
42
|
{"alias": "taken", "label": "Taken", "color": "slate"}, {"alias": "baking", "label": "Baking", "color": "amber"},
|
|
@@ -58,54 +58,53 @@ One call, linked tables together; a call names a table by its alias, a new table
|
|
|
58
58
|
"amount": {"type": "formula", "label": "Amount", "expression": "{quantity} * {unit_price}", "notation": {"style": "currency", "currency": "USD"}}
|
|
59
59
|
},
|
|
60
60
|
"unique": [["order", "item"]],
|
|
61
|
-
"records": {"
|
|
61
|
+
"records": {"figure": "amount"}
|
|
62
62
|
}
|
|
63
63
|
]
|
|
64
64
|
}
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
`
|
|
67
|
+
`default_from` copies the menu's price when a line is made, so a later change leaves taken orders alone. `min`, `unique` and a check hold on every write; a check's language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). Every key: `reference/tables`.
|
|
68
68
|
|
|
69
69
|
## 2. The paper: `set_template`
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
An Act names a template by its alias, made from its name (`order_slip`), so the paper comes first.
|
|
72
72
|
|
|
73
73
|
```
|
|
74
74
|
set_template {"type": "html", "name": "Order slip",
|
|
75
|
-
"template": "<h1>
|
|
75
|
+
"template": "<h1>{{reference}}</h1><p>{{customer}}, {{date due_on}}</p>{{#each lines}}<p>{{item}} × {{quantity}}</p>{{/each}}<p>{{money total \"USD\"}}</p>",
|
|
76
76
|
"variables": {"reference": "string", "customer": "string", "due_on": "string", "lines": "array", "total": "string"}}
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
One template per paper the owner sends. A slot is named after a field of the record; the cakes loop under the name of the link to them (`lines`). More: `document_templates`.
|
|
80
80
|
|
|
81
81
|
## 3. The app and its acts: `set_app`
|
|
82
82
|
|
|
83
|
-
**Which apps.** One app per main entity,
|
|
84
|
-
|
|
85
|
-
**The view per kind of row** is chosen before writing the List, from `design/treatments`: cards for things found by their photo, a calendar or lanes for dated work, faces for people and organisations, `sort` on the date a list is worked by. Every screen is judged against the visual bar `design` opens on.
|
|
83
|
+
**Which apps.** One app per main entity, a thing people work from its own list (customers, items, orders, employees), and everything that belongs to a row on that row's page. A row that makes sense only under one parent (an employee's contracts, an order's lines) is a child List on the parent's page, never another app or a Tab. An order may stand in the orders app and on its customer's page: one record, one page. A second root List is rare: one job working two unrelated entities side by side. A related row's value on the list is a lookup column; work over many rows (a month's payroll) an Act on the list's rows.
|
|
86
84
|
|
|
87
|
-
**
|
|
85
|
+
**The view per kind of row** comes before the List: read `design/treatments` first.
|
|
88
86
|
|
|
89
|
-
|
|
87
|
+
**Start from one root List.** `{"type": "List", "entity": "cake_order"}` in the App's `children` is a whole app: the platform draws the page every row opens, the add and the Delete. `set_app` answers with what it drew and what it placed or folded; state only the difference.
|
|
90
88
|
|
|
91
89
|
```json
|
|
92
90
|
{
|
|
93
91
|
"body": {
|
|
94
|
-
"type": "App", "key": "counter", "name": "Counter",
|
|
92
|
+
"type": "App", "key": "counter", "name": "Counter",
|
|
95
93
|
"children": [
|
|
96
|
-
{"type": "List", "entity": "cake_order", "filters": ["customer"], "create": ["customer", "due_on", "pay_by"]
|
|
94
|
+
{"type": "List", "entity": "cake_order", "filters": ["customer"], "create": ["customer", "due_on", "pay_by"], "children": [
|
|
95
|
+
{"type": "Reading", "key": "by_pickup", "label": "By pickup day", "value": "total", "by": "due_on"}
|
|
96
|
+
]}
|
|
97
97
|
],
|
|
98
98
|
"pages": [
|
|
99
|
-
{"type": "Record", "entity": "cake_order", "
|
|
100
|
-
{"type": "Section", "
|
|
99
|
+
{"type": "Record", "entity": "cake_order", "children": [
|
|
100
|
+
{"type": "Section", "title": "Order", "at": ["taken", "baking"], "children": [
|
|
101
101
|
"due_on",
|
|
102
102
|
"pay_by",
|
|
103
103
|
{"type": "List", "entity": "cake_line", "create": ["item", "quantity"]},
|
|
104
104
|
{"type": "Act", "key": "start_baking", "label": "Start baking", "when": {"stage": ["taken"]}, "requires": ["due_on"], "asks": ["prepaid"], "set": {"stage": "baking"}},
|
|
105
105
|
{"type": "Act", "key": "ready", "label": "Ready", "when": {"stage": ["baking"]}, "set": {"stage": "ready"}, "template": "order_slip", "into": "slip"}
|
|
106
106
|
]},
|
|
107
|
-
{"type": "Section", "
|
|
108
|
-
{"field": "balance", "edit": false},
|
|
107
|
+
{"type": "Section", "title": "Pickup", "at": ["ready"], "children": [
|
|
109
108
|
{"field": "slip", "edit": false},
|
|
110
109
|
{"type": "Act", "key": "collect", "label": "Collected", "when": {"stage": ["ready"], "paid": true}, "set": {"stage": "collected"}}
|
|
111
110
|
]}
|
|
@@ -115,46 +114,48 @@ One app, the counter's job, over the tables and template above. The register lis
|
|
|
115
114
|
}
|
|
116
115
|
```
|
|
117
116
|
|
|
118
|
-
|
|
117
|
+
**Give each main List a band** of what its person watches, a figure or a chart in its `children`, never a bare count.
|
|
118
|
+
|
|
119
|
+
**A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), at the foot of the Section of the stage it leaves. **Someone with no seat** who signs or approves one record, a customer or a supplier, gets a Record's `Outside`: a link a member makes of that record (`reference/outside-node`).
|
|
119
120
|
|
|
120
|
-
|
|
121
|
-
|
|
121
|
+
**What the check refuses**, each with its page at `reference/<id>`:
|
|
122
|
+
|
|
123
|
+
- `record.placed-once`: a Field, child List, Reading, Statement or Act stands once in a Record. The head draws the title, subtitle, image and figure; the status is a control in the first Section that runs the moves.
|
|
124
|
+
- `list.filter-unshown`: a `filters` entry (at most 3), or the field a Reading's `by` or `where` narrows by, is drawn on the row; never text, and the status is the chips already.
|
|
122
125
|
- `list.columns-budget`: `columns` fit the room a desk leaves beside the name, status, deadline and figure.
|
|
123
126
|
- `act.requires-drawn`: an Act's `requires` field is drawn in its Section or asked by it.
|
|
124
|
-
- `act.makes-or-runs`: an Act makes a `template` or runs a `workflow`.
|
|
125
|
-
- `app.names-declared`: each alias a key names exists (a table, field, option, Act `key`, template).
|
|
126
127
|
- A workflow writes a link as ids, `[x.id]`; a whole record or bare value is refused.
|
|
127
128
|
|
|
128
|
-
Then `set_access` gives
|
|
129
|
-
|
|
130
|
-
```
|
|
131
|
-
set_access {"resources": [{"resource_type": "app", "resource_id": "app_…"}], "principals": [{"principal_type": "member", "principal_id": "<member id>", "role": "user"}]}
|
|
132
|
-
```
|
|
129
|
+
Then `set_access` gives each app to the people whose job it is (ids from `get_workspace`); none loses access. They need no table access, and with no `rows` on the App they read every row.
|
|
133
130
|
|
|
134
131
|
## 4. What the owner will ask an agent: Query and Workflow nodes
|
|
135
132
|
|
|
136
|
-
|
|
133
|
+
What the business asks its assistant again and again (orders waiting for pickup) is a Query or Workflow node of the app, with a `description` for an agent that has not seen the screen (`agent_surface` § Declaring more). A connected service is reached by a Workflow node's step (`workflows`).
|
|
137
134
|
|
|
138
135
|
## 5. The owner's rows: `create_records`
|
|
139
136
|
|
|
140
|
-
|
|
137
|
+
Batch the owner's rows: the customers and menu, then the orders, linked by the ids those calls return, then each order's cakes (`field_values` has the value each type takes). Load as an admin: a row past the first stage (`records.status.stages`) is refused unless that stage's owner or an admin makes it. Example rows the papers ask for and do not list come from the owner's lists, marked as examples, each at the stage it should show; never a placeholder where the owner's rows exist.
|
|
141
138
|
|
|
142
139
|
```
|
|
143
|
-
create_records {"table_id": "menu_item", "field_keys": ["name", "price"], "rows": [["Lemon cake", 24], ["Chocolate cake", 28]]}
|
|
144
|
-
create_records {"table_id": "customer", "field_keys": ["name"], "rows": [["Ana Lopez"]]}
|
|
145
|
-
create_records {"table_id": "cake_order", "field_keys": ["customer", "due_on", "pay_by"], "rows": [["<Ana's record id>", "2031-03-14", "2031-03-12"]]}
|
|
146
140
|
create_records {"table_id": "cake_line", "field_keys": ["order", "item", "quantity"],
|
|
147
|
-
"rows": [["<
|
|
141
|
+
"rows": [["<the order's record id>", "<Lemon cake's record id>", 2]]}
|
|
148
142
|
```
|
|
149
143
|
|
|
150
144
|
## 6. Verify: `run_app_workflow`, `screenshot_app`
|
|
151
145
|
|
|
152
|
-
Move the owner's
|
|
153
|
-
|
|
146
|
+
Move the owner's rows through the app as their person would, each only as far as the stage the owner says it is at, and judge each shot against the visual bar `design` opens on. An Act runs as `act_<key>` (or under the alias of the `workflow` it names), handed what it asks. A dry run walks the moves and files nothing; then press each paper Act for real, on one row the owner's stage allows or on an example row left at its last stage: what is left on a row is what the owner opens. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`: it shows a member's view and reads, which is how each person's screen is checked.
|
|
154
147
|
```
|
|
155
148
|
run_app_workflow {"app_id": "app_…", "alias": "act_start_baking", "inputs": {"record_id": "rec_…", "prepaid": 20}, "dry_run": true}
|
|
156
|
-
|
|
157
|
-
screenshot_app {"app_id": "app_…"}
|
|
149
|
+
screenshot_app {"app_id": "app_…", "as_member": "<member id>"}
|
|
158
150
|
```
|
|
159
151
|
|
|
160
|
-
|
|
152
|
+
## 7. Hand over
|
|
153
|
+
|
|
154
|
+
Leave standing instructions with `set_workspace` (`instructions`, one entry per rule): who the business is, its people's words, what any agent here must keep to. As an admin, invite the people named with `set_members` (`members` keyed by email, role `member` or `admin`), else say whom to invite.
|
|
155
|
+
|
|
156
|
+
Before you report:
|
|
157
|
+
|
|
158
|
+
- Go through the owner's message and papers line by line and find each thing they named on a shot, as the person who uses it, at phone and desk width.
|
|
159
|
+
- Read each paper the presses made for a blank.
|
|
160
|
+
|
|
161
|
+
Put right or name each gap. Then show the owner what you built, job by job, each paper and what makes it, with the choices you made for them to change.
|
package/docs/workflows.md
CHANGED
|
@@ -27,8 +27,8 @@ ones that follow or name them.
|
|
|
27
27
|
| automation | `on({ type: "recurring_schedule", cron_expression })`, `receive_webhook`, `receive_gmail_email` or `receive_outlook_email` — see **Automations** |
|
|
28
28
|
| app | `on({ type: "app", app_id, alias, inputs?, outputs? })` — `inputs` and `outputs` only for a custom-code app |
|
|
29
29
|
|
|
30
|
-
What starts a workflow is fixed once it is made: a table workflow
|
|
31
|
-
app and alias. To change either, delete the workflow and make another. A replace states the whole trigger, so a key the
|
|
30
|
+
What starts a workflow is fixed once it is made: its kind, a table workflow's trigger type and table, an automation's
|
|
31
|
+
trigger type, an app workflow's app and alias. To change either, delete the workflow and make another. A replace states the whole trigger, so a key the
|
|
32
32
|
header leaves out is removed (an app workflow keeps the inputs it leaves out, and derives the outputs it leaves out from
|
|
33
33
|
what the body returns). `expected_version` refuses a replace when the workflow has moved since the `version` you read.
|
|
34
34
|
`dry_run` checks the source and stores nothing; given the trial inputs its trigger supplies, it also walks the steps once
|
|
@@ -194,7 +194,12 @@ A body names a table or document template by its alias (`query_records({ table_i
|
|
|
194
194
|
refusal's `field_errors` and a `validate` check's `field_key` name a declared input or a field's alias.
|
|
195
195
|
5. **`==` against a multi-select means "includes".** `record["tags"] == "urgent"` on a multi-select is stored as
|
|
196
196
|
`includes(record["tags"], "urgent")`; either spelling works.
|
|
197
|
-
6.
|
|
197
|
+
6. **`option("<field>", "<option>")` names an option where no select is beside it** (a name set once and compared later,
|
|
198
|
+
a list of options, a value handed to a tool). It reads as the option, typed as that select's, and is stored as its key.
|
|
199
|
+
The field is looked up among the tables the body reaches; a field or option that does not exist is refused naming both, and
|
|
200
|
+
a field alias that two tables state with different keys for that option is refused naming each table. A key
|
|
201
|
+
option key written out still works, but write `option()`: a key is a value no one can read.
|
|
202
|
+
7. **Text renders labels.** Inside a template or a text tool input, a select, member or link value renders its display
|
|
198
203
|
text: `` `${record["status"]}` `` writes "Done", not `done`, and `` `${record["status"] ?? ""}` `` writes it too. A
|
|
199
204
|
formula stating `options` (a computed category) is read as the single select it is drawn as: compared by option,
|
|
200
205
|
rendered by label.
|
|
@@ -472,8 +477,8 @@ sheet into its plants, and keeps each sheet and its lines. A line names its plan
|
|
|
472
477
|
holding many rows: one holding a single row would make the line that plant's own, and a plant its
|
|
473
478
|
lines belong to is not moved to the trash.
|
|
474
479
|
|
|
475
|
-
These tables are shown beside the plants, in the same app: the sheets as a
|
|
476
|
-
(a
|
|
480
|
+
These tables are shown beside the plants, in the same app: the sheets as a List beside the plants'
|
|
481
|
+
(a second List at the root, `reference/app-node`), a sheet's lines on the page it opens. A line keeping what a cell held
|
|
477
482
|
and what it holds now in two fields reads one against the other (`compare`, `reference/list-node`).
|
|
478
483
|
|
|
479
484
|
```
|
|
@@ -74,7 +74,7 @@ No tool resolves a business name to its tax ID. The customer's own papers carry
|
|
|
74
74
|
invoicing footer, a contract, a past invoice. A web search limited to registry listings (`masothue.com`,
|
|
75
75
|
`infodoanhnghiep.com`) shows each match's tax ID in its result, though those sites refuse a direct fetch; many companies
|
|
76
76
|
share a name, and the registered address is what tells them apart. For a
|
|
77
|
-
Vietnamese tax ID (
|
|
77
|
+
Vietnamese tax ID (a branch's with a `-00N` suffix), `https://api.vietqr.io/v2/business/{tax_id}` answers the
|
|
78
78
|
registered name, address and status (`NNT đang hoạt động` when active); it is rate-limited, answering 429 to a burst. A
|
|
79
79
|
registered address can differ from the one a PO prints.
|
|
80
80
|
|