@lotics/cli 0.321.15 → 0.321.17
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 +21 -15
- package/docs/build.md +2 -2
- package/docs/design.md +49 -6
- package/docs/examples.md +3 -15
- package/docs/workflow_steps.md +4 -3
- package/docs/workflows.md +2 -0
- package/docs/working_in_a_workspace.md +1 -1
- package/package.json +1 -1
package/docs/build.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
Build from this page, `design` and the treatment the rows call for; a refusal names the `reference/<id>` page for the rest. 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
|
-
`get_workspace` shows what already exists and `get_app` an app's tree: an app added or changed later starts there and states only the difference (`reference/changing-an-app`). Each write to an app makes a new version of it, and the live app is the only copy; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. Before the first write, send the person who asked one message covering: the jobs and lists this business runs beyond those named, the trade's usual ones stated as defaults that stand; who does each job (`get_workspace` kind `member` lists the organization's people, not who works in this business or what each does); and the lists and papers they already keep, attached. A busy owner answers what comes first, so the message's first line is its first question, and it asks only what their papers and your defaults cannot settle, among them the papers they keep, asked by what they hold, and what else they keep track of; the defaults come after. "Go ahead" is a full answer. No second round: build from the answer. A short request names a business, not everything it runs on, so the workspace holds what that kind of business can't run without, such as what must never happen, what people are paid for and the papers it sends; your report names what you assumed, for them to change. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
|
|
5
|
+
`get_workspace` shows what already exists and `get_app` an app's tree: an app added or changed later starts there and states only the difference (`reference/changing-an-app`). Each write to an app makes a new version of it, and the live app is the only copy; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. Before the first write, send the person who asked one message covering: the jobs and lists this business runs beyond those named, the trade's usual ones stated as defaults that stand; who does each job (`get_workspace` kind `member` lists the organization's people, not who works in this business or what each does); and the lists and papers they already keep, attached. A busy owner answers what comes first, so the message's first line is its first question, and it asks only what their papers and your defaults cannot settle, among them the papers they keep, asked by what they hold, and what else they keep track of; the defaults come after. "Go ahead" is a full answer. No second round: build from the answer, and a paper or list that does not come with it is never waited for — build from your defaults now and say in your report which papers would sharpen it. A short request names a business, not everything it runs on, so the workspace holds what that kind of business can't run without, such as what must never happen, what people are paid for and the papers it sends; your report names what you assumed, for them to change. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
|
|
6
6
|
|
|
7
7
|
## 1. Tables and their checks: `set_tables`
|
|
8
8
|
|
|
9
|
-
Linked tables go in one call, since they name each other by `ref`; `records` and checks may follow in the next call, so a refusal costs a patch rather than the whole document. 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 (`data_model`). A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row's face, picture and mark are stated there. Over rows already there, read a sample before building on a field: one mostly empty holds up no screen. 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).
|
|
9
|
+
Linked tables go in one call, since they name each other by `ref`; `records` and checks may follow in the next call, so a refusal costs a patch rather than the whole document. 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 (`data_model`). A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row's face, picture and mark are stated there, and so is what goes wrong on a row and needs someone to act: an issue (`design/issues`). Over rows already there, read a sample before building on a field: one mostly empty holds up no screen. 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
10
|
|
|
11
11
|
```json
|
|
12
12
|
{
|
package/docs/design.md
CHANGED
|
@@ -12,10 +12,9 @@ or its entity is read-only (`edit: false`); a stepped status never is, since Act
|
|
|
12
12
|
- Each app looks like its own rows: the view its kind of row takes (`design/treatments`) — cards for things found by
|
|
13
13
|
their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn
|
|
14
14
|
as one, the most common failure of an app; the answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt where rows wait on one another).
|
|
15
|
-
- What needs attention leads the row as
|
|
16
|
-
tone on the row's line (in the danger tone where
|
|
17
|
-
success tone. `records.mark` is a category's own mark, a select whose options carry a brand or glyph.
|
|
18
|
-
once, on the entity it is true of: every List over those rows offers it in one filter of Checks, with how many hold it, and its `on` may name an Act of a record that lists them whole, through a List whose link is paired; the act holds those rows and the record first, so it cannot also send mail, notify, run an agent or wait in its own `workflow` — start that work from a workflow the act starts after.
|
|
15
|
+
- What needs attention leads the row as an issue its table declares (`design/issues`): a derived flag is an issue, in the
|
|
16
|
+
warning tone on the row's line (in the danger tone where a Check's `on` refuses an act the row offers); every other yes
|
|
17
|
+
reads in the success tone. `records.mark` is a category's own mark, a select whose options carry a brand or glyph.
|
|
19
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
|
|
20
19
|
fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields
|
|
21
20
|
the row's name to the subtitle's first part and stands first on its line.
|
|
@@ -180,7 +179,7 @@ or its entity is read-only (`edit: false`); a stepped status never is, since Act
|
|
|
180
179
|
**Check**
|
|
181
180
|
|
|
182
181
|
- `field` (alias, required): A yes/no or text formula of the page's entity
|
|
183
|
-
- `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing
|
|
182
|
+
- `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing issue refuses
|
|
184
183
|
- `resolve` (alias): An Act on one row of this entity that clears it
|
|
185
184
|
|
|
186
185
|
**Reading**
|
|
@@ -194,6 +193,49 @@ or its entity is read-only (`edit: false`); a stepped status never is, since Act
|
|
|
194
193
|
|
|
195
194
|
<!-- generated:end words -->
|
|
196
195
|
|
|
196
|
+
## Issues
|
|
197
|
+
|
|
198
|
+
Whatever goes wrong on a row and needs a person to act — a line delivered short, a price missing, a customer over their
|
|
199
|
+
credit limit, a permit about to expire — is an issue its table declares in `records.issues`. A declared issue stands in
|
|
200
|
+
every app that draws its row, with no app stating it: first on the row's line (`+N` the others), in the record's
|
|
201
|
+
callout, in the List's filter of what needs checking with how many rows hold it, and those rows first. It never makes an
|
|
202
|
+
app draw a row it did not, and never shows on an `Outside` page. What needs no one's action is no issue: a stage is the
|
|
203
|
+
status, a category a select.
|
|
204
|
+
|
|
205
|
+
- An issue is a formula of the row stating `output_type`: `"boolean"` stands while true; `"text"` stands while not empty,
|
|
206
|
+
its words the sentence the reader sees — use it when the sentence must say what or how much ("Short 4 of 10").
|
|
207
|
+
Its label is its name. Put the moment it matters in the formula, so it clears itself when the work is done.
|
|
208
|
+
- The list is priority: an issue blocking the next step leads, then the earlier in the list.
|
|
209
|
+
- `{ "rows": <link> }` on a parent rolls up every issue its child table declares, through a many-link paired to the
|
|
210
|
+
child's one-row link back. The platform keeps a count on the parent per child issue, `<link>_<issue>`, labelled
|
|
211
|
+
"<link label> · <issue label>"; never write it. The parent reads "2 rows left: Lines · Short".
|
|
212
|
+
- A formula reading `now()` or `isToday()` (overdue, expiring within 30 days) is judged again every night, to the day.
|
|
213
|
+
- An app's `Check` says what the issue does not: `on`, what it refuses in that app (`"update"`, `"all"`, or that
|
|
214
|
+
entity's Acts), and `resolve`, the Act that clears it; one stating neither is refused, and one without `on` names a
|
|
215
|
+
declared issue. A parent's Act is refused by a Check on the parent's count `on` that Act (never `"update"` or `"all"`: editing the rows clears it); the act then holds
|
|
216
|
+
the parent while it runs, so its own `workflow` cannot send mail, notify, run an agent or wait — start that work from a
|
|
217
|
+
workflow the act starts after.
|
|
218
|
+
- A lock is a Check, not an issue: a yes/no such as paid in full refusing `"update"`, in no `records.issues`, since nothing
|
|
219
|
+
is wrong with the row.
|
|
220
|
+
- `get_table` reports each issue: rows holding it now, opened in the last 30 days, median days to clear.
|
|
221
|
+
|
|
222
|
+
An order whose lines can arrive short or unpriced, invoiced only when no line is short:
|
|
223
|
+
|
|
224
|
+
```json5
|
|
225
|
+
// order_line
|
|
226
|
+
"fields": {
|
|
227
|
+
"short": { "label": "Short", "type": "formula", "output_type": "text",
|
|
228
|
+
"expression": "!isEmpty({delivered}) && {delivered} < {quantity} ? \"Short \" + toString({quantity} - {delivered}) + \" of \" + toString({quantity}) : \"\"" },
|
|
229
|
+
"no_price": { "label": "No price", "type": "formula", "output_type": "boolean", "expression": "isEmpty({price})" }
|
|
230
|
+
},
|
|
231
|
+
"records": { "issues": ["short", "no_price"] }
|
|
232
|
+
// order — `lines` is its many-link to order_line; the platform adds lines_short and lines_no_price
|
|
233
|
+
"records": { "issues": [{ "rows": "lines" }] }
|
|
234
|
+
// the order's Record in the app
|
|
235
|
+
{ "type": "Check", "field": "lines_short", "on": ["invoice"] },
|
|
236
|
+
{ "type": "Check", "field": "paid_in_full", "on": ["update"] }
|
|
237
|
+
```
|
|
238
|
+
|
|
197
239
|
## Look at it
|
|
198
240
|
|
|
199
241
|
After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` or its `record_id`
|
|
@@ -207,12 +249,13 @@ send the tree saved before the change as `body` with `app_id`, nulling an App pr
|
|
|
207
249
|
|
|
208
250
|
Whether the build does the owner's work, answered by a call each, never from what you meant to write:
|
|
209
251
|
|
|
210
|
-
1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`).
|
|
252
|
+
1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`); one who cannot open the app is first invited (`set_members`) and given it (`set_access`) — an app nobody shares opens for admins alone.
|
|
211
253
|
2. Can an agent do each job in one call, an `act_<key>` or a Query or Workflow node whose `description` names it? `get_app` lists them; `run_app_workflow` with `dry_run` proves one (`agent_surface/prove-an-app-as-an-agent`).
|
|
212
254
|
3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.
|
|
213
255
|
4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?
|
|
214
256
|
5. Is anything cramped at desk or phone width?
|
|
215
257
|
6. Is every paper and every Export made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove an Export with `run_app_query` and `export`.
|
|
258
|
+
7. Is each thing that must never happen in this business (a step taken before its approval, stock below zero, a double booking) refused on every write? Prove each with a write sent `dry_run: true` that is refused (`workflows/table-checks`).
|
|
216
259
|
|
|
217
260
|
A failed answer is a change to the tree, or a gap named to the owner.
|
|
218
261
|
|
package/docs/examples.md
CHANGED
|
@@ -766,7 +766,6 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
766
766
|
"credit_limit": {"type": "number", "notation": {"style": "currency", "currency": "USD"}},
|
|
767
767
|
"orders": {"type": "link", "table": "order", "multi": true},
|
|
768
768
|
"outstanding": {"type": "rollup"},
|
|
769
|
-
"over_limit": {"type": "formula"},
|
|
770
769
|
"papers_needed": {
|
|
771
770
|
"type": "select",
|
|
772
771
|
"options": [
|
|
@@ -824,7 +823,6 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
824
823
|
"delivery_note": {"type": "files"},
|
|
825
824
|
"notes": {"type": "text", "format": "markdown"},
|
|
826
825
|
"paid_in_full": {"type": "formula"},
|
|
827
|
-
"has_payments": {"type": "formula"},
|
|
828
826
|
"reminder_ref": {"type": "text"}
|
|
829
827
|
},
|
|
830
828
|
"records": {
|
|
@@ -1011,8 +1009,7 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
1011
1009
|
"title": "Contact log",
|
|
1012
1010
|
"children": [{"type": "List", "entity": "touch", "layout": "timeline"}]
|
|
1013
1011
|
},
|
|
1014
|
-
{"type": "Section", "key": "notes", "title": "Notes", "children": ["notes"]}
|
|
1015
|
-
{"type": "Check", "field": "over_limit"}
|
|
1012
|
+
{"type": "Section", "key": "notes", "title": "Notes", "children": ["notes"]}
|
|
1016
1013
|
]
|
|
1017
1014
|
},
|
|
1018
1015
|
{
|
|
@@ -1034,8 +1031,7 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
1034
1031
|
"delivery_note",
|
|
1035
1032
|
"notes",
|
|
1036
1033
|
{"field": "reminder_ref", "edit": false},
|
|
1037
|
-
{"type": "Check", "field": "paid_in_full", "on": ["update"]}
|
|
1038
|
-
{"type": "Check", "field": "has_payments"}
|
|
1034
|
+
{"type": "Check", "field": "paid_in_full", "on": ["update"]}
|
|
1039
1035
|
]
|
|
1040
1036
|
},
|
|
1041
1037
|
{"type": "Record", "entity": "warehouse", "add": ["name", "city"]},
|
|
@@ -1132,8 +1128,6 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
1132
1128
|
"ngay_sinh": {"type": "lookup"},
|
|
1133
1129
|
"da_thu": {"type": "rollup"},
|
|
1134
1130
|
"chua_thu_phi": {"type": "formula"},
|
|
1135
|
-
"con_no_phi": {"type": "formula"},
|
|
1136
|
-
"vuot_thu_nhap": {"type": "formula"},
|
|
1137
1131
|
"da_hoan_tat": {"type": "formula"}
|
|
1138
1132
|
},
|
|
1139
1133
|
"records": {
|
|
@@ -1440,8 +1434,6 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
1440
1434
|
"paper": "giay_to.xac_nhan_thu_nhap"
|
|
1441
1435
|
},
|
|
1442
1436
|
{"type": "Check", "field": "chua_thu_phi", "on": ["nop_cdt"]},
|
|
1443
|
-
{"type": "Check", "field": "con_no_phi"},
|
|
1444
|
-
{"type": "Check", "field": "vuot_thu_nhap"},
|
|
1445
1437
|
{"type": "Check", "field": "da_hoan_tat", "on": ["doc_giay_to"]}
|
|
1446
1438
|
],
|
|
1447
1439
|
"row": {"figure": false}
|
|
@@ -1879,8 +1871,6 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
1879
1871
|
"phieu_chi": {"type": "files"},
|
|
1880
1872
|
"ngan_sach_du_an": {"type": "lookup"},
|
|
1881
1873
|
"da_duyet_du_an": {"type": "lookup"},
|
|
1882
|
-
"vuot_ngan_sach": {"type": "formula"},
|
|
1883
|
-
"sat_ngan_sach": {"type": "formula"},
|
|
1884
1874
|
"da_gui": {"type": "formula"},
|
|
1885
1875
|
"nhap_at": {"type": "date", "format": "datetime"},
|
|
1886
1876
|
"cho_duyet_at": {"type": "date", "format": "datetime"},
|
|
@@ -1997,9 +1987,7 @@ among them: the `design` reference. Every key: `reference`, at the pages each se
|
|
|
1997
1987
|
"at": ["da_chi"],
|
|
1998
1988
|
"children": [{"field": "phieu_chi", "edit": false}]
|
|
1999
1989
|
},
|
|
2000
|
-
{"type": "Check", "field": "da_gui", "on": ["update"]}
|
|
2001
|
-
{"type": "Check", "field": "vuot_ngan_sach"},
|
|
2002
|
-
{"type": "Check", "field": "sat_ngan_sach"}
|
|
1990
|
+
{"type": "Check", "field": "da_gui", "on": ["update"]}
|
|
2003
1991
|
]
|
|
2004
1992
|
},
|
|
2005
1993
|
{"type": "Record", "entity": "du_an", "add": ["ten", "ma_du_an", "chu_dau_tu", "ngan_sach"]}
|
package/docs/workflow_steps.md
CHANGED
|
@@ -2154,7 +2154,7 @@ above. A provider's refusal carries the provider's own words.
|
|
|
2154
2154
|
### get_record (workflow step)
|
|
2155
2155
|
|
|
2156
2156
|
- Fetch a single record with all field values.
|
|
2157
|
-
- Returns data (raw values) and display (human-readable labels).
|
|
2157
|
+
- Returns data (raw values) and display (human-readable labels); a workflow body's read carries `display`, `links`, `comment_count` and `units` only when the body reads them.
|
|
2158
2158
|
- A workspace admin's `as_member` fetches it as that member would see it.
|
|
2159
2159
|
- Cell shapes in `data`, keyed by field alias: select / member / link, and a formula with options, read back as arrays — a single-select as ["open"], the option's alias; one member as ["mbr_x"].
|
|
2160
2160
|
- A workflow body reads the same single-select, single-member or option-formula cell as the bare value, and a files cell as a list of file objects, each with id, filename and mime_type: `first(record.file).id` is the id a file tool takes.
|
|
@@ -2174,11 +2174,12 @@ above. A provider's refusal carries the provider's own words.
|
|
|
2174
2174
|
| Name | Type | Required | What it is |
|
|
2175
2175
|
| --- | --- | --- | --- |
|
|
2176
2176
|
| `id` | string | yes | |
|
|
2177
|
+
| `table_id` | string | yes | |
|
|
2177
2178
|
| `data` | object | yes | |
|
|
2178
|
-
| `display` | object |
|
|
2179
|
+
| `display` | object | | Human-readable display values for select, member, and record link fields. Omitted from a workflow read whose body never looks at it. |
|
|
2179
2180
|
| `links` | object | | Each link field's linked rows with the title the cell carries, by field alias; `data` holds their ids. |
|
|
2180
2181
|
| `locked` | boolean | | |
|
|
2181
|
-
| `comment_count` | number |
|
|
2182
|
+
| `comment_count` | number | | How many comments the record holds. Omitted from a workflow read whose body never looks at it. |
|
|
2182
2183
|
| `comments` | object[] | | With `comments: true`: the newest first. |
|
|
2183
2184
|
| `comments[].id` | string | yes | Unique identifier for the comment |
|
|
2184
2185
|
| `comments[].member_id` | string | yes | ID of the member who created this comment |
|
package/docs/workflows.md
CHANGED
|
@@ -111,6 +111,8 @@ The name in `const x = await tool({...})` is the step's id; later expressions re
|
|
|
111
111
|
`x.records`, `x.id` and so on. A `// id: my_step` comment directly above a statement sets an explicit
|
|
112
112
|
id; any other `//` comment there becomes the step's description.
|
|
113
113
|
|
|
114
|
+
A run reads a repeated identical record read once, until the run writes; a loop that waits for a row to change needs a `wait` step, or each pass sees the same rows.
|
|
115
|
+
|
|
114
116
|
**`await` inside a statement** runs the call as its own step first, then reads its output where it is
|
|
115
117
|
written: `size((await query_records({...})).records)`, an `if` test, a `return` value, a `for-of`
|
|
116
118
|
iterable, a tool input. `const x = c ? await t({...}) : null;` is stored as the `if` it means. An
|
|
@@ -29,7 +29,7 @@ Find the means in this order: `get_workspace` maps the workspace; `search` it by
|
|
|
29
29
|
|
|
30
30
|
## Comments
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
A record read carries `comment_count` (a workflow body gets it when it reads it). `query_records` takes `comments: true` to return the thread (`limit` defaults to 20, 20 at most). Comments are written by people, on the record in Lotics or through the product's chat.
|
|
33
33
|
|
|
34
34
|
## Deleting and restoring
|
|
35
35
|
|