@lotics/cli 0.318.21 → 0.318.23
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 +2 -2
- package/dist/src/cli.js +16 -11
- package/docs/app_architecture.md +21 -19
- package/docs/building_an_app.md +1 -1
- package/docs/design.md +45 -47
- package/docs/first_build.md +5 -22
- package/docs/getting_started.md +1 -1
- package/package.json +1 -1
package/docs/app_architecture.md
CHANGED
|
@@ -1,26 +1,28 @@
|
|
|
1
1
|
# App architecture — a worked split
|
|
2
2
|
|
|
3
|
-
The
|
|
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, since it decides who sees what.
|
|
4
4
|
|
|
5
|
-
One furniture factory,
|
|
5
|
+
One furniture factory, five people, seven apps:
|
|
6
6
|
|
|
7
|
-
| App (
|
|
8
|
-
|
|
9
|
-
|
|
|
10
|
-
|
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
7
|
+
| App (its list) | Opened by | On a row's page |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Customers | Sales rep, owner | Their prices, orders and unpaid invoices |
|
|
10
|
+
| Products | Sales rep, foreman | Price breaks, bill of materials, stock on hand |
|
|
11
|
+
| Orders | Sales rep, foreman, owner | Lines, the quote paper (an Act), the work orders it starts |
|
|
12
|
+
| Work orders | Foreman | Steps, the Acts that move a stage, the inspection |
|
|
13
|
+
| Suppliers | Buyer | Their price list and purchase orders |
|
|
14
|
+
| Purchase orders | Buyer, storekeeper | Lines, goods received |
|
|
15
|
+
| Materials | Storekeeper, buyer | Movements in and out, the Receive and Issue Acts |
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
|
|
17
|
+
An order's lines, a work order's steps and a customer's prices make sense only under their parent: each is a child
|
|
18
|
+
List on that row's page, never an app or a Tab. An order stands in the Orders app and on its customer's page: one
|
|
19
|
+
record, one page. The owner reads the figures each register leads with. Each app's `name` is its list and its `description` says what is worked there:
|
|
18
20
|
|
|
19
21
|
```json
|
|
20
22
|
{
|
|
21
23
|
"type": "App",
|
|
22
|
-
"key": "
|
|
23
|
-
"name": "
|
|
24
|
+
"key": "orders",
|
|
25
|
+
"name": "Orders",
|
|
24
26
|
"description": "Takes a customer's order from quote to dispatch.",
|
|
25
27
|
"children": [{ "type": "List", "entity": "order" }]
|
|
26
28
|
}
|
|
@@ -29,11 +31,11 @@ looked up or opened inside the job that uses it. Each app's `name` and `descript
|
|
|
29
31
|
```json
|
|
30
32
|
{
|
|
31
33
|
"type": "App",
|
|
32
|
-
"key": "
|
|
33
|
-
"name": "
|
|
34
|
-
"description": "
|
|
35
|
-
"children": [{ "type": "List", "entity": "
|
|
34
|
+
"key": "customers",
|
|
35
|
+
"name": "Customers",
|
|
36
|
+
"description": "Each customer's prices, orders and what they owe.",
|
|
37
|
+
"children": [{ "type": "List", "entity": "customer" }]
|
|
36
38
|
}
|
|
37
39
|
```
|
|
38
40
|
|
|
39
|
-
Then `set_access` gives
|
|
41
|
+
Then `set_access` gives each person only the apps beside their name (`first_build`, § 3). How each tree is composed is `design`.
|
package/docs/building_an_app.md
CHANGED
|
@@ -218,7 +218,7 @@ you registered once (`lotics docs document_templates`).
|
|
|
218
218
|
## 7 — Look at it, then name it
|
|
219
219
|
|
|
220
220
|
Look at every app you apply, at a desktop width and at a phone's — every check above reads the
|
|
221
|
-
definition, none of them the pixels:
|
|
221
|
+
definition, none of them the pixels — and judge each shot against the visual bar `design` opens on:
|
|
222
222
|
|
|
223
223
|
```
|
|
224
224
|
lotics run screenshot_app '{"app_id":"app_…"}' -o ./shots
|
package/docs/design.md
CHANGED
|
@@ -1,31 +1,61 @@
|
|
|
1
1
|
# Designing an app
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The
|
|
4
|
+
tree states COMPOSITION — which fields, lists and acts each job's screen holds; how each piece looks is the platform's,
|
|
5
|
+
one way per concept. A node the tree leaves out draws its default, from the table's facts (`records`, the stage, the
|
|
6
|
+
write rules): a List's Readings band, the stage buttons, the picture, a Record's Sections. State a node to change it,
|
|
7
|
+
or `false` at it to turn it off (`"readings": false`, `"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. Each prop's keys are in `reference`, a treatment
|
|
9
|
+
worked in a whole workspace is `examples/<treatment>`, and which apps a business needs is `first_build`, § 3.
|
|
10
|
+
|
|
11
|
+
**The visual bar.** Every screen is judged against it; a miss is a change to the tree.
|
|
12
|
+
|
|
13
|
+
- Each app looks like its own rows: the view its kind of row takes (`design/treatments`) — cards for things found by
|
|
14
|
+
their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn
|
|
15
|
+
as one, the most common failure of an app; the answer of `set_app` notes what the rows call for that no default draws.
|
|
16
|
+
- What needs attention leads the row: `records.mark` on a select or a computed category (a formula stating its options;
|
|
17
|
+
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
|
+
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 one or two columns the job reads on every row. Each
|
|
20
|
+
fact once: no column repeats the mark, status, subtitle or title.
|
|
21
|
+
- A list worked by a date states `sort` on that date's column, newest first; without one, a register reads newest made
|
|
22
|
+
first and a record's child List in the order its rows were added.
|
|
23
|
+
- Someone is a face wherever they are read: a link to a table stating `records.party` draws its row's face; a member
|
|
24
|
+
field is one already; select options naming people or organisations who are neither each take the `mark`
|
|
25
|
+
`{"kind": "avatar", "name": "person"}`, never a colour dot.
|
|
26
|
+
- A thing shows its picture, a file its preview, a plan its days on a time axis, a quantity a meter (`records.limits`) or
|
|
27
|
+
a chart, a register its Readings, and long text reads whole (a markdown Field; `block: true` on plain long text).
|
|
28
|
+
- Every category the job reads is coloured: each option's `color`, and a `mark` where a brand or glyph names it, on
|
|
29
|
+
every option of a select read down a column (how it was paid, the channel).
|
|
30
|
+
- Every app states its tile's `color`, apart from the workspace's other apps where it can be.
|
|
31
|
+
- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the
|
|
32
|
+
carrier, the authority) in the Section where that work happens, kept visible after its stage, and the source of a
|
|
33
|
+
figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere.
|
|
34
|
+
|
|
35
|
+
**Each shot answers:** can the person find their row? Is what needs doing first, on the row's lead? Is anything
|
|
36
|
+
repeated or empty? Is anyone shown without their face? Is every paper visible? Across the workspace: can each app be
|
|
37
|
+
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.
|
|
4
38
|
|
|
5
|
-
|
|
39
|
+
## Look at it
|
|
6
40
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
`"row": { "image": false }`). A Field the screens draw is a control, a save, unless it states `edit: false`: an entity drawn read-only gets none, and a stepped status is never a default edit, since Acts move it. A List left as a table is drawn as one, even where a calendar, a face or a picture would
|
|
14
|
-
answer the reader at a glance, and that is the most common failure of an app: the answer of `set_app` notes what the
|
|
15
|
-
rows call for that no default draws (rows in time, a template's Act, a timeline), and the tree states the ones the job
|
|
16
|
-
needs.
|
|
41
|
+
After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` (`screen`
|
|
42
|
+
for a later screen of a long one) — at a desk's width and a phone's, naming the columns a table left off at each width;
|
|
43
|
+
`-o <dir>` saves the shots from the CLI. Beside them, `verdict` is what a write of the stored tree would be refused for
|
|
44
|
+
now, and its notes. Answer the questions of the visual bar, change the tree with `nodes`, and write again. To go back,
|
|
45
|
+
send the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
|
|
46
|
+
`period`, `icon`); tables and rows stay as they are.
|
|
17
47
|
|
|
18
48
|
## Treatments
|
|
19
49
|
|
|
20
|
-
A treatment named
|
|
21
|
-
|
|
22
|
-
author: state the ones the job needs. A note refuses nothing.
|
|
50
|
+
A treatment named below is one the answer of `set_app` notes when the rows call for it and nothing draws it, naming the
|
|
51
|
+
node that would state it; a note refuses nothing. Each kind of row's view is chosen before its List is written:
|
|
23
52
|
|
|
24
53
|
| The rows are | The treatment | Its props |
|
|
25
54
|
|---|---|---|
|
|
26
55
|
| People or organisations | `records.party`, with a photo or logo as its `image` | `reference/records` |
|
|
27
56
|
| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/records`, `reference/cards` |
|
|
28
57
|
| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
|
|
58
|
+
| Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | `reference/list-node` |
|
|
29
59
|
| Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` | `reference/lanes`, `reference/write-rules` |
|
|
30
60
|
| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |
|
|
31
61
|
| 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 | `reference/section-node` |
|
|
@@ -283,35 +313,3 @@ through its own declared workflows. It stands alone with `label` and `when`, on
|
|
|
283
313
|
in a Record's section, or a compose `Act` piece naming it). The target must be an app of the workspace that reaches the
|
|
284
314
|
record's table — a register over it, or custom code declaring no table or declaring it; anything else is refused at
|
|
285
315
|
save. A reader without `use` on the target meets that app's own "cannot open" state.
|
|
286
|
-
|
|
287
|
-
## The visual bar
|
|
288
|
-
|
|
289
|
-
- A person shows a face, a thing its picture, a file its preview, a plan its days on a time axis, a
|
|
290
|
-
quantity a meter (`records.limits`) or a chart, a register its Readings under its title, and long text
|
|
291
|
-
reads whole (a markdown Field is a prose block; `block: true` makes a plain long text one).
|
|
292
|
-
- Every app states its tile's colour (the App's `color`), apart from the workspace's other apps where it can be,
|
|
293
|
-
so the launcher tells the desks apart before their names are read.
|
|
294
|
-
- Every category the job reads is coloured: each select option's `color`, and a `mark` where a brand or a
|
|
295
|
-
glyph names it — on every option of a select read down a column (how it was paid, the channel, the mode).
|
|
296
|
-
- A yes that needs attention (papers the customer still owes) is a `Check` of its List over a yes/no formula, so it
|
|
297
|
-
reads in the warning tone on the row's line; every other yes reads in the success tone.
|
|
298
|
-
- Someone is a face wherever they are read. A person is a member field and a party a row of a table stating
|
|
299
|
-
`party`; where a select's options name people or organisations who are neither, every option's `mark` is
|
|
300
|
-
its face (`{"kind": "avatar", "name": "person"}`), never a colour dot.
|
|
301
|
-
- Every files field is drawn somewhere — a Section's Fields, a Field of the Record, the `image`, or where the
|
|
302
|
-
Act making it stands.
|
|
303
|
-
- The paperwork is the proof of the work, so every paper the job takes in and every document it issues has a
|
|
304
|
-
place on the record, in the Section where that work happens: a files field per purpose (what arrived, what
|
|
305
|
-
was issued to the customer, to the carrier, to the authority), each kept visible after the stage that made it,
|
|
306
|
-
and a source — a screenshot, an email, a sheet — on the row whose figure came from it.
|
|
307
|
-
- A screen with none of these is bland, and bland is a finding: text drawn where a treatment above exists
|
|
308
|
-
is a change to the tree.
|
|
309
|
-
|
|
310
|
-
## Look at it
|
|
311
|
-
|
|
312
|
-
After an apply, the `screenshot_app` tool draws each app as its people see it — the register, and a record
|
|
313
|
-
by its `path` — at a desk's width and a phone's, one screen a shot, naming the columns a table left off at
|
|
314
|
-
each width: `screen` names which screen of a long record. From the CLI, `-o <dir>` saves the shots. Beside the shots, `verdict` is what a write of the app's stored tree would refuse it for now, beside its rows, and
|
|
315
|
-
the notes on it. Judge each shot against § The visual bar, change the tree with `nodes`, and write again. To go back,
|
|
316
|
-
send the tree you saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
|
|
317
|
-
`period`, `icon`); the tables and rows stay as they are.
|
package/docs/first_build.md
CHANGED
|
@@ -80,26 +80,9 @@ Every paper the owner sends is made, one template each. A slot is named after a
|
|
|
80
80
|
|
|
81
81
|
## 3. The app and its acts: `set_app`
|
|
82
82
|
|
|
83
|
-
**Which apps.** One per
|
|
84
|
-
|
|
85
|
-
**The view per kind of row
|
|
86
|
-
|
|
87
|
-
| The rows are | The treatment | Keys |
|
|
88
|
-
|---|---|---|
|
|
89
|
-
| People or organisations | `records.party`, photo or logo as `image` | `reference/records` |
|
|
90
|
-
| Photos people look at | `records.image`; List `layout: "cards"` | `reference/cards` |
|
|
91
|
-
| Held on a day people schedule by | List `layout: "calendar"` | `reference/calendar` |
|
|
92
|
-
| Booked on a resource over time | List `layout: {"lanes": {"by": …}}`, table `no_overlap` | `reference/lanes` |
|
|
93
|
-
| Standing at places on a floor or yard | List `layout: {"plan": …}` | `reference/plan` |
|
|
94
|
-
| People across days | List `layout: "roster"`, the cells' List inside | `reference/roster` |
|
|
95
|
-
| Expected against counted, before against after | a List with `compare: {"before": …, "after": …}` | `reference/list-node` |
|
|
96
|
-
| Ranked by a figure | List `sort: {"field": …, "desc": true}` | `reference/list-node` |
|
|
97
|
-
| Moved through a status (stages) | an Act per move, `status.dates`, Readings | `reference/act-node` |
|
|
98
|
-
| Each belonging to another row | a child List on its page | `reference/list-node` |
|
|
99
|
-
| Counted over a period | Tabs over one `period`; Readings | `reference/tab-node` |
|
|
100
|
-
| Papers a case gathers | a List with `expect`; an Act's `template` | `reference/list-node` |
|
|
101
|
-
|
|
102
|
-
Any other screen: `design/treatments`.
|
|
83
|
+
**Which apps.** One app per main entity, and everything that belongs to a row on that row's page. A main entity is a thing people work from its own list (customers, items, orders, suppliers, employees), each its own app, people and organisations included. What belongs to one row (an employee's contracts, payslips and leave; an order's lines; a customer's prices and balance) is a child List on that row's page, never another app or a Tab. The test: a row that stands alone and is picked from its own list is an app; a row that makes sense only under one parent is on the parent's page. One record may stand in both, an order 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. Each person is given only the few apps their job uses. A related row's value on the list (the newest contract's end)? A lookup column. Work over many rows (a month's payroll)? An Act on the list's rows. Here: the counter (orders), the menu and the customers; the counter is built below.
|
|
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.
|
|
103
86
|
|
|
104
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 (a Section per stage with its moves, the cakes as a child List), the add and the Delete. `set_app` answers with what it drew and what it placed or folded in what you stated; state only the difference. The tree below states this counter's choices.
|
|
105
88
|
|
|
@@ -132,7 +115,7 @@ One app, the counter's job, over the tables and template above. The register lis
|
|
|
132
115
|
}
|
|
133
116
|
```
|
|
134
117
|
|
|
135
|
-
`set_app` answers with a note for what the rows call for that the tree leaves out. It places what has one fix and stores the placed tree: a reader's `where` moved to `opens
|
|
118
|
+
`set_app` answers with a note for what the rows call for that the tree leaves out. It places what has one fix and stores the placed tree: a reader's `where` moved to `opens` and a `row.subtitle` made `columns`. These fold with one note: a read-only copy of a placed Field, `create`/`remove: false` on a read-only List, its `app` where one app is over its table, a lone text field's `unique`, a patch address unlike the node's `key`. **What the check refuses**, each with its id (`reference/<id>` is its page; some show a wrong → right):
|
|
136
119
|
|
|
137
120
|
- `record.placed-once`: a Field, child List, Reading, Statement or Act stands once in a Record, whose head draws the title, subtitle, image, status, figure; a read-only repeat is left out and said.
|
|
138
121
|
- `list.filter-unshown`: a `filters` entry (at most 3) is a select, member, link, date, yes/no or number the rows show, or a formula of such; never text, and the status is the chips already.
|
|
@@ -166,7 +149,7 @@ create_records {"table_id": "cake_line", "field_keys": ["order", "item", "quanti
|
|
|
166
149
|
|
|
167
150
|
## 6. Verify: `run_app_workflow`, `screenshot_app`
|
|
168
151
|
|
|
169
|
-
Move the owner's own rows through the app as their person would, in stage order. An Act runs as `act_<key>` (or under the alias of the `workflow` it names), handed what it asks; dry-run first, then press. To prove a rule, send the write with `dry_run: true`; never make a test row or switch a check off. A row ends at the stage the owner says it is at, so press each only that far; where the owner gave no rows, ask for a few.
|
|
152
|
+
Move the owner's own rows through the app as their person would, in stage order, 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; dry-run first, then press. To prove a rule, send the write with `dry_run: true`; never make a test row or switch a check off. A row ends at the stage the owner says it is at, so press each only that far; where the owner gave no rows, ask for a few.
|
|
170
153
|
|
|
171
154
|
```
|
|
172
155
|
run_app_workflow {"app_id": "app_…", "alias": "act_start_baking", "inputs": {"record_id": "rec_…", "prepaid": 20}, "dry_run": true}
|
package/docs/getting_started.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Getting started
|
|
2
2
|
|
|
3
|
-
A workspace is where one business keeps what it knows and does its daily work. **Records** are what it tracks, one table per kind of thing and one row per entry. **Apps** are the screens a team works in, one per
|
|
3
|
+
A workspace is where one business keeps what it knows and does its daily work. **Records** are what it tracks, one table per kind of thing and one row per entry. **Apps** are the screens a team works in, one per main kind of record, each person given the few their job uses. **Documents** are the quotes, invoices and slips it sends, each a template filled from a record, or from the many rows of a period or a statement. A paper is the workspace's once it is made from a template or uploaded and filed on its record; a file left on the host's own disk, the user's included, reaches no one in the workspace. A procedure or policy no table holds is a **knowledge doc**; a price list, a customer list or the open orders are rows.
|
|
4
4
|
|
|
5
5
|
Open the one page for the job. Pages are read with the `docs` tool (`docs path="design"`; `lotics docs design` on the CLI).
|
|
6
6
|
|