@lotics/cli 0.321.96 → 0.321.98
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 +442 -351
- package/dist/src/client.d.ts +9 -0
- package/dist/src/client.js +32 -19
- package/docs/agent_surface.md +4 -9
- package/docs/app_bindings.md +6 -8
- package/docs/cli_reference.md +2 -2
- package/docs/design.md +6 -6
- package/docs/document_templates.md +6 -20
- package/docs/examples.md +7 -14
- package/docs/workflows.md +22 -9
- package/docs/working_in_a_workspace.md +1 -1
- package/package.json +1 -1
package/dist/src/client.d.ts
CHANGED
|
@@ -223,6 +223,15 @@ export declare class NoAnswerError extends Error {
|
|
|
223
223
|
* because the clock covers the body too.
|
|
224
224
|
*/
|
|
225
225
|
export declare function fetchStorage<T>(url: string, timeoutMs: number | undefined, read: (response: Response) => Promise<T>): Promise<T>;
|
|
226
|
+
/**
|
|
227
|
+
* Saves the body of an object-storage signed URL to a file as it arrives, never holding it whole: the one way a link
|
|
228
|
+
* becomes a file. `fileFor` reads the response's status and headers and names the absolute `file` to write (with
|
|
229
|
+
* whatever else its caller answers), creating nothing; its directory is created here. Held to `timeoutMs` as
|
|
230
|
+
* `fetchStorage` holds a read, body included.
|
|
231
|
+
*/
|
|
232
|
+
export declare function saveStorageLink<T extends {
|
|
233
|
+
file: string;
|
|
234
|
+
}>(url: string, timeoutMs: number | undefined, fileFor: (response: Response) => Promise<T>): Promise<T>;
|
|
226
235
|
/**
|
|
227
236
|
* The website: where a person goes when the CLI cannot finish the job. Held
|
|
228
237
|
* beside the API base and overridable for the same reason — a run against a
|
package/dist/src/client.js
CHANGED
|
@@ -78,7 +78,7 @@ function telemetryErrorMessage(status, parsed) {
|
|
|
78
78
|
|
|
79
79
|
// ../shared/src/cli_capabilities.ts
|
|
80
80
|
var CLI_CAPABILITIES_HEADER = "x-lotics-cli-capabilities";
|
|
81
|
-
var CLI_CAPABILITIES = ["docs-fallback", "answer-file"];
|
|
81
|
+
var CLI_CAPABILITIES = ["docs-fallback", "answer-file", "answer-link"];
|
|
82
82
|
|
|
83
83
|
// ../shared/src/proxy_upload_limit.ts
|
|
84
84
|
var PROXY_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
|
|
@@ -87,6 +87,8 @@ var PROXY_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
|
|
|
87
87
|
import crypto from "node:crypto";
|
|
88
88
|
import fs from "node:fs";
|
|
89
89
|
import path from "node:path";
|
|
90
|
+
import { Readable } from "node:stream";
|
|
91
|
+
import { pipeline } from "node:stream/promises";
|
|
90
92
|
|
|
91
93
|
// src/invocation.ts
|
|
92
94
|
var invocation = null;
|
|
@@ -193,6 +195,22 @@ async function fetchStorage(url, timeoutMs, read) {
|
|
|
193
195
|
throw error;
|
|
194
196
|
}
|
|
195
197
|
}
|
|
198
|
+
async function saveStorageLink(url, timeoutMs, fileFor) {
|
|
199
|
+
return fetchStorage(url, timeoutMs, async (response) => {
|
|
200
|
+
const target = await fileFor(response);
|
|
201
|
+
await fs.promises.mkdir(path.dirname(target.file), { recursive: true });
|
|
202
|
+
const body = response.body === null ? Readable.from([]) : Readable.fromWeb(response.body);
|
|
203
|
+
const partial = `${target.file}.${crypto.randomUUID()}.part`;
|
|
204
|
+
try {
|
|
205
|
+
await pipeline(body, fs.createWriteStream(partial));
|
|
206
|
+
} catch (error) {
|
|
207
|
+
await fs.promises.rm(partial, { force: true });
|
|
208
|
+
throw error;
|
|
209
|
+
}
|
|
210
|
+
await fs.promises.rename(partial, target.file);
|
|
211
|
+
return target;
|
|
212
|
+
});
|
|
213
|
+
}
|
|
196
214
|
var NEVER_SENT_CODES = /* @__PURE__ */ new Set([
|
|
197
215
|
"ENOTFOUND",
|
|
198
216
|
"ECONNREFUSED",
|
|
@@ -551,14 +569,11 @@ var LoticsClient = class {
|
|
|
551
569
|
return this.requestForm("POST", `/v1/apps/${encodeURIComponent(args.app_id)}/versions`, formData);
|
|
552
570
|
}
|
|
553
571
|
async downloadFile(url, outputPath) {
|
|
554
|
-
const
|
|
572
|
+
const { file } = await saveStorageLink(url, this.timeoutMs, async (response) => {
|
|
555
573
|
if (!response.ok) throw new Error(`${response.status}: Failed to download file`);
|
|
556
|
-
return
|
|
574
|
+
return { file: path.resolve(outputPath) };
|
|
557
575
|
});
|
|
558
|
-
|
|
559
|
-
await fs.promises.mkdir(path.dirname(absolutePath), { recursive: true });
|
|
560
|
-
await fs.promises.writeFile(absolutePath, buffer);
|
|
561
|
-
return absolutePath;
|
|
576
|
+
return file;
|
|
562
577
|
}
|
|
563
578
|
/**
|
|
564
579
|
* One page of this workspace's stored files, newest first — `GET /v1/files`.
|
|
@@ -577,20 +592,17 @@ var LoticsClient = class {
|
|
|
577
592
|
}
|
|
578
593
|
async downloadFileById(fileId, destination, options) {
|
|
579
594
|
const { url } = await this.request("GET", `/v1/files/${encodeURIComponent(fileId)}/signed_url`);
|
|
580
|
-
const
|
|
595
|
+
const saved = await saveStorageLink(url, this.timeoutMs, async (response) => {
|
|
581
596
|
if (!response.ok) await this.throwResponseError(response);
|
|
582
|
-
|
|
597
|
+
const originalFilename = parseContentDispositionFilename(response.headers.get("content-disposition") ?? "") ?? fileId;
|
|
598
|
+
const { dir, named } = destination === void 0 ? { dir: process.cwd() } : "file" in destination ? {
|
|
599
|
+
dir: path.dirname(path.resolve(destination.file)),
|
|
600
|
+
named: path.basename(destination.file)
|
|
601
|
+
} : { dir: path.resolve(destination.dir) };
|
|
602
|
+
const filename = named ?? findAvailableFilename(dir, originalFilename, options?.reserved);
|
|
603
|
+
return { file: path.join(dir, filename), filename, stored_filename: originalFilename };
|
|
583
604
|
});
|
|
584
|
-
|
|
585
|
-
const { dir, named } = destination === void 0 ? { dir: process.cwd() } : "file" in destination ? {
|
|
586
|
-
dir: path.dirname(path.resolve(destination.file)),
|
|
587
|
-
named: path.basename(destination.file)
|
|
588
|
-
} : { dir: path.resolve(destination.dir) };
|
|
589
|
-
await fs.promises.mkdir(dir, { recursive: true });
|
|
590
|
-
const filename = named ?? findAvailableFilename(dir, originalFilename, options?.reserved);
|
|
591
|
-
const absolutePath = path.join(dir, filename);
|
|
592
|
-
await fs.promises.writeFile(absolutePath, buffer);
|
|
593
|
-
return { path: absolutePath, filename, stored_filename: originalFilename };
|
|
605
|
+
return { path: saved.file, filename: saved.filename, stored_filename: saved.stored_filename };
|
|
594
606
|
}
|
|
595
607
|
async downloadRecordFiles(recordId, fieldAlias, outputDir) {
|
|
596
608
|
const result = await this.execute("query_records", { record_ids: [recordId] }, { format: "text" });
|
|
@@ -767,5 +779,6 @@ export {
|
|
|
767
779
|
fetchStorage,
|
|
768
780
|
findAvailableFilename,
|
|
769
781
|
pollCliLogin,
|
|
782
|
+
saveStorageLink,
|
|
770
783
|
startCliLogin
|
|
771
784
|
};
|
package/docs/agent_surface.md
CHANGED
|
@@ -46,8 +46,6 @@ app has.
|
|
|
46
46
|
| `<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a List stating `same`; `record_<field>` per `where` bound to a field of the record | each Reading of a Record page, each List that only reads on it (its `key`, else its entity's alias) and each funnel, called by its `key` |
|
|
47
47
|
| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading's | a Reading whose value `records.limits` bounds: the bound's sum, beside the Reading's own |
|
|
48
48
|
| `<reading>_on_hand` | <label> / <on-hand entity>: how many <on-hand entity> rows there are, per "<field>". Each row carries `<field>`, `__count`. | none: every row of its entity its `where` keeps, whatever the place | a Reading with `on_hand` (a shortfall): the on-hand rows' groups, beside the Reading's own |
|
|
49
|
-
| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | an Export of the register that fills a template |
|
|
50
|
-
| `<entity>_export_rows_of_<source>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | an Export over some of a List's sources: their rows alone, each source named in turn |
|
|
51
49
|
| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |
|
|
52
50
|
| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads — the rows with no <place> counted apart. | | a register laid out as a `plan`: its places' counts of present rows |
|
|
53
51
|
|
|
@@ -140,19 +138,16 @@ read over; a tab's totals take the folder's id too, in an app that works inside
|
|
|
140
138
|
## Exporting a file
|
|
141
139
|
|
|
142
140
|
```
|
|
143
|
-
run_app_query {"app_id":"app_…","export":{"
|
|
141
|
+
run_app_query {"app_id":"app_…","export":{"list":"by_carrier","tab":"in_yard","status":["…"]}}
|
|
144
142
|
```
|
|
145
143
|
|
|
146
|
-
`export` makes
|
|
147
|
-
file like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `key` is
|
|
148
|
-
|
|
149
|
-
read. An option is named by its name or its id, as a read's filters name it; a member by its id or its name, for a member
|
|
150
|
-
of the app's organization; a row, by its id. The other keys
|
|
144
|
+
`export` makes a List that states `export: true` as a workbook, as the register's Export button does, from what the caller reads, and answers it under `files` as a workspace
|
|
145
|
+
file like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `list` is the View id of that List: its `key` at the root, `<page entity>.<key>` below a row's page (the row page's table, a dot, the List's `key`); it is sent without `alias` or any other argument of a
|
|
146
|
+
read. An option is named by its name or its id, as a read's filters name it; a member by its id; a row, by its id. The other keys
|
|
151
147
|
narrow the file as the register's own controls do, each absent one leaving the register's opening view:
|
|
152
148
|
|
|
153
149
|
| Key | Takes |
|
|
154
150
|
|---|---|
|
|
155
|
-
| `per` | The option, row id or member id the report is made for — required by an Export that states `per`, refused by one that does not; a member, here and in a member chip, is an id or a name, found as a filter on a member column finds one |
|
|
156
151
|
| `tab`, `period`, `window` | A Tab's key (the first when absent); `{ "from", "to" }` days `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` on a date-and-time field) the tabs read over; a calendar's or board's days |
|
|
157
152
|
| `status` | Options of the register's status that are kept |
|
|
158
153
|
| `filters` | `{ "<field>": <value> }` by the field's alias, a value `null` clearing the register's opening chip; a value is one of the shapes below |
|
package/docs/app_bindings.md
CHANGED
|
@@ -31,7 +31,7 @@ A `Query` node reads one table or List with `rows` or `list`. A wider read state
|
|
|
31
31
|
|
|
32
32
|
## Queries
|
|
33
33
|
|
|
34
|
-
A query declaration is `{ ast, params?, description
|
|
34
|
+
A query declaration is `{ ast, params?, description? }`:
|
|
35
35
|
|
|
36
36
|
- `ast` — a query template (a QueryNode, below). It fixes the tables, filters and columns the alias
|
|
37
37
|
reads, so a caller cannot widen it.
|
|
@@ -41,18 +41,16 @@ A query declaration is `{ ast, params?, description?, templates? }`:
|
|
|
41
41
|
param left unset drops the conditions that read it; a required param that arrives empty is
|
|
42
42
|
refused where a filter reads it.
|
|
43
43
|
- `description` — one line saying what the query returns, for an agent choosing between aliases.
|
|
44
|
-
- `templates` — the document templates an export of its rows may fill, by name:
|
|
45
|
-
`{ <name>: { template_id: "dtl_…", rows: "<key the template lists the rows under>" } }`.
|
|
46
44
|
|
|
47
45
|
A save checks what a deploy checks: every table is in this workspace and within the owner's reach,
|
|
48
46
|
every projected, filtered and sorted field resolves, every param token is declared, and a key a
|
|
49
47
|
node's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.
|
|
50
48
|
|
|
51
|
-
`set_app` states one as a `Query` node: `{ "type": "Query", "key": "<alias>", "ast": { … } }`, beside `params
|
|
52
|
-
|
|
53
|
-
replaces its `ast
|
|
54
|
-
code, `nodes` takes `{ "<alias>": { … } }` and merges each: send only the fields you change, `null` clears `params
|
|
55
|
-
|
|
49
|
+
`set_app` states one as a `Query` node: `{ "type": "Query", "key": "<alias>", "ast": { … } }`, beside `params`
|
|
50
|
+
and `description`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch
|
|
51
|
+
replaces its `ast` or `params` whole. On an app that serves
|
|
52
|
+
code, `nodes` takes `{ "<alias>": { … } }` and merges each: send only the fields you change, `null` clears `params`
|
|
53
|
+
or `description` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its
|
|
56
54
|
`children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by
|
|
57
55
|
name, and `get_app`'s `body` reads them back by alias.
|
|
58
56
|
|
package/docs/cli_reference.md
CHANGED
|
@@ -29,9 +29,9 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
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
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
|
-
| — | **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: {"
|
|
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: {"list", …narrowing}` instead of the read arguments makes the workbook of a List that states `export: true`, `list` its View id (`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
|
-
| `lotics run <tool> '<json>'` with `as_file: true` | An answer that names its own file (`_file`) is saved as that file
|
|
34
|
+
| `lotics run <tool> '<json>'` with `as_file: true` | An answer that names its own file (`_file`) is saved as that file where the command runs, or in `-o <dir>`: a page's as the whole JSON answer, a whole set's (`query_records` with no page, or `all: true`) downloaded from `_file.url` as it arrives, JSON Lines. The path prints after the answer (on stderr under `--json`). The same call names the same file, so running it again replaces it. |
|
|
35
35
|
| `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`. |
|
|
36
36
|
| `lotics run set_members '{"members": {"<email or member id>": {"role": "member", "name": "…"}}}'` | Invite to this workspace (`name` is the name the invitation carries) or set a person's role in it (`role`: `member` or `admin`; `null` takes the person, or the invitation pending to that address, out of it); `groups` keeps the member groups in the same call. An admin of this workspace or an organization owner. Renaming or removing a person, restoring one, co-ownership and a member who signs in by a name are a person's in Settings → Members, and no tool takes them. The whole input is checked before an email is sent. A member's `lotics tools` lists neither `set_members` nor `set_workspace`. View-as is the web app's preview alone; the CLI acts as the signed-in member. |
|
|
37
37
|
| `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |
|
package/docs/design.md
CHANGED
|
@@ -128,8 +128,8 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
128
128
|
- `create` (boolean | list of alias (at least one)): The fields an add asks
|
|
129
129
|
- `columns` (list of (alias | Edit column)): Fields read after the row's title, each drawn though no row holds it
|
|
130
130
|
- `label` (text): The register's name in the app's lists and tab strip
|
|
131
|
-
- `filters` (list of (alias | Tiered filter | Listed filter)
|
|
132
|
-
- `children` (list of (Tab | Reading |
|
|
131
|
+
- `filters` (list of (alias | Tiered filter | Listed filter)): Fields the reader narrows by every day, beside the stage chips
|
|
132
|
+
- `children` (list of (Tab | Reading | Act | List) (at least one)): Its Tabs, band Readings and Acts over ticked rows or every row in view
|
|
133
133
|
- `key` (alias): Names the List among its siblings and in a Query's `list`
|
|
134
134
|
- `sort` (Sort key | list of Sort key (at least one)): The rows' order
|
|
135
135
|
- `layout` (layout): A word, or an object stating one layout with its data
|
|
@@ -143,7 +143,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
143
143
|
**Record**
|
|
144
144
|
|
|
145
145
|
- `entity` (alias, required): The table whose rows open on this page
|
|
146
|
-
- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps holding the Sections that are its path),
|
|
146
|
+
- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps holding the Sections that are its path), and the Fields, Fieldsets, Lists, Readings, Statements and Comments stated directly
|
|
147
147
|
- `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
|
|
148
148
|
- `row` (Record row): How the App reads this entity's rows wherever it lists them
|
|
149
149
|
- `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer
|
|
@@ -260,7 +260,7 @@ Whether the build does the owner's work, answered by a call each, never from wha
|
|
|
260
260
|
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.
|
|
261
261
|
4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?
|
|
262
262
|
5. Is anything cramped at desk or phone width?
|
|
263
|
-
6. Is every paper and every
|
|
263
|
+
6. Is every paper and every exporting List's workbook made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove a List's `export: true` with `run_app_query` and `export`.
|
|
264
264
|
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`).
|
|
265
265
|
|
|
266
266
|
A failed answer is a change to the tree, or a gap named to the owner.
|
|
@@ -284,7 +284,7 @@ Each kind of row's view is chosen before its List is written:
|
|
|
284
284
|
| 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, and every row's ⋯ offers Duplicate; a List with `same` where read-only | |
|
|
285
285
|
| 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` |
|
|
286
286
|
| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | |
|
|
287
|
-
| 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 reads only what was true at the period's end, never a status the row moves on from | |
|
|
287
|
+
| 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 | |
|
|
288
288
|
| Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | |
|
|
289
289
|
| A plan of spans | List `layout: {"gantt": {"start": …}}` | `reference/gantt` |
|
|
290
290
|
| Stood at a place on a plan, flat or in 3D — pallets, bins | List `layout: {"plan": …}`; places state `plan_place` | `reference/plan` |
|
|
@@ -377,7 +377,7 @@ register's outline is. A child List on a record with this layout draws the bars
|
|
|
377
377
|
`layout: "roster"` with a List inside it over the child whose rows fill the days — one link back to the
|
|
378
378
|
register's table and a date on its line: what each row did on each day (shifts, runs, attendance). With
|
|
379
379
|
`expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.
|
|
380
|
-
|
|
380
|
+
Worked: `examples/roster`.
|
|
381
381
|
|
|
382
382
|
#### Weekly pattern
|
|
383
383
|
|
|
@@ -87,6 +87,9 @@ this host, give the person the file and a `person` drop link.
|
|
|
87
87
|
(skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass
|
|
88
88
|
raw numbers, ISO dates and booleans at generate time; the cell's number format shows them. A cell's format also decides
|
|
89
89
|
what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).
|
|
90
|
+
A date cell reads a day or a moment written with no zone (`2026-09-30T08:15`) as that clock, and a moment written with
|
|
91
|
+
one (a workflow's `now()`, `2026-09-30T08:15:00+07:00`) on the workspace's clock; `format`, `add_days` and a
|
|
92
|
+
comparison read it the same way.
|
|
90
93
|
- **`word`** — a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,
|
|
91
94
|
`{{FOR … IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added
|
|
92
95
|
(`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run
|
|
@@ -103,7 +106,7 @@ Every type supports three shapes of substitution. The exact syntax differs per e
|
|
|
103
106
|
the `set_template` description for the reference; here is the capability:
|
|
104
107
|
|
|
105
108
|
- **Scalar** — a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in
|
|
106
|
-
Excel preserve their type via the cell's number format.
|
|
109
|
+
Excel preserve their type via the cell's number format, and an Excel cell whose template prints nothing (empty text, only spaces, or no value) is left blank.
|
|
107
110
|
- **Repeating rows / line items** — one template row rendered once per item in a list, for
|
|
108
111
|
invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style
|
|
109
112
|
`{{#each items}}…{{/each}}`; Word uses `{{FOR item IN items}}…{{$item.field}}…{{END-FOR item}}`. The HTML and email types
|
|
@@ -210,7 +213,7 @@ siblings in the List's order, with its depth as `level` (1 for the rows filed un
|
|
|
210
213
|
A paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the
|
|
211
214
|
titles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is
|
|
212
215
|
refused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no
|
|
213
|
-
column
|
|
216
|
+
column. A Word template is read for this when it is next saved.
|
|
214
217
|
|
|
215
218
|
A paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one file of them all: the rows arrive under the entity's alias. An html paper hands each row the child rows the record's paper would be handed, under the same names, with their `_totals`; an Excel or Word paper is handed the rows alone. The page the rows open draws those Lists:
|
|
216
219
|
|
|
@@ -218,26 +221,9 @@ A paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one
|
|
|
218
221
|
{{#each supplier_order}}<h2>{{code}}</h2>{{#each sources}}<p>{{description}} × {{quantity}}</p>{{/each}}{{/each}}
|
|
219
222
|
```
|
|
220
223
|
|
|
221
|
-
A paper over many rows (a client's month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act's `template
|
|
224
|
+
A paper over many rows (a client's month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act's `template`. A report that reads rows of its own choosing and fills a template is an Act that runs a Workflow calling `generate_document` (`reference/act-node`, `reference/workflow-node`, `workflows/steps`); the Workflow hands the file back to whoever pressed the Act.
|
|
222
225
|
`reference/groups-and-templates` has the rest.
|
|
223
226
|
|
|
224
|
-
A roster's `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days
|
|
225
|
-
holding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List's entity alias, `student` here)
|
|
226
|
-
`cells`, a word per column — each of its rows' mark, the option's `short` else its label (a row with no state, its title), joined by `, ` —
|
|
227
|
-
`counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row's figure, else the count of the cells it holds):
|
|
228
|
-
|
|
229
|
-
```html
|
|
230
|
-
<tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>
|
|
231
|
-
{{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
| | A | B | C | D | E |
|
|
235
|
-
|---|---|---|---|---|---|
|
|
236
|
-
| 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |
|
|
237
|
-
| 2 | `{{#each student}}` | | | | |
|
|
238
|
-
| 3 | `{{name}}` | | `{{cells \| lookup:@index}}` | | `{{counts.absent}}` |
|
|
239
|
-
| 4 | `{{/each}}` | | | | |
|
|
240
|
-
|
|
241
227
|
## Discovering and managing templates
|
|
242
228
|
|
|
243
229
|
These tools work across all five types:
|
package/docs/examples.md
CHANGED
|
@@ -567,14 +567,9 @@ each section says which its record takes under **Its stages**, so the form is co
|
|
|
567
567
|
"create": ["ho_ten", "chuyen_mon", "dien_thoai"],
|
|
568
568
|
"children": [
|
|
569
569
|
{"type": "List", "entity": "lich_truc", "create": true, "remove": true},
|
|
570
|
-
{"type": "Act", "key": "tao_ca_truc_ds", "label": "Tạo ca trực", "on": "view", "makes": "lich_truc"}
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
"key": "lich_truc_thang",
|
|
574
|
-
"label": "Lịch trực tháng",
|
|
575
|
-
"template": "lich_truc_thang"
|
|
576
|
-
}
|
|
577
|
-
]
|
|
570
|
+
{"type": "Act", "key": "tao_ca_truc_ds", "label": "Tạo ca trực", "on": "view", "makes": "lich_truc"}
|
|
571
|
+
],
|
|
572
|
+
"export": true
|
|
578
573
|
}
|
|
579
574
|
],
|
|
580
575
|
"pages": [
|
|
@@ -688,10 +683,8 @@ each section says which its record takes under **Its stages**, so the form is co
|
|
|
688
683
|
"filters": ["on_hand"],
|
|
689
684
|
"search": ["name", "sku"],
|
|
690
685
|
"layout": "cards",
|
|
691
|
-
"children": [
|
|
692
|
-
|
|
693
|
-
{"type": "Export", "key": "export"}
|
|
694
|
-
]
|
|
686
|
+
"children": [{"type": "Reading", "key": "register_reading_0", "value": "on_hand", "by": "category"}],
|
|
687
|
+
"export": true
|
|
695
688
|
}
|
|
696
689
|
],
|
|
697
690
|
"pages": [
|
|
@@ -1290,7 +1283,6 @@ each section says which its record takes under **Its stages**, so the form is co
|
|
|
1290
1283
|
"over": "ngay_nhan_giay_to"
|
|
1291
1284
|
},
|
|
1292
1285
|
{"type": "Reading", "key": "register_reading_2", "by": "doi_tuong"},
|
|
1293
|
-
{"type": "Export", "key": "export"},
|
|
1294
1286
|
{
|
|
1295
1287
|
"type": "Act",
|
|
1296
1288
|
"key": "in_danh_sach",
|
|
@@ -1298,7 +1290,8 @@ each section says which its record takes under **Its stages**, so the form is co
|
|
|
1298
1290
|
"on": "view",
|
|
1299
1291
|
"template": "danh_sach_nop"
|
|
1300
1292
|
}
|
|
1301
|
-
]
|
|
1293
|
+
],
|
|
1294
|
+
"export": true
|
|
1302
1295
|
},
|
|
1303
1296
|
{
|
|
1304
1297
|
"type": "List",
|
package/docs/workflows.md
CHANGED
|
@@ -123,6 +123,10 @@ id; any other `//` comment there becomes the step's description.
|
|
|
123
123
|
|
|
124
124
|
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.
|
|
125
125
|
|
|
126
|
+
A `query_records` with no `limit` returns the first 50 rows, and `has_more` says whether there are more. `all: true` returns every row the call matches, up to 32 MiB of them; a call past that is refused, with no rows. `all` does not combine with `limit`, `offset`, `page_size`, `pagination`, `record_ids`, `aggregate`, `tables` or `comments`, and a workflow's read takes no `as_file`.
|
|
127
|
+
|
|
128
|
+
`sort` of a records read also takes `__created_at` and `__updated_at`, a row's creation and last-update time (`{ field_key: "__created_at", order: "desc" }` is newest-created first); with `include_timestamps: true` each row carries `created_at` and `updated_at`, read as `r.created_at`.
|
|
129
|
+
|
|
126
130
|
**`await` inside a statement** runs the call as its own step first, then reads its output where it is
|
|
127
131
|
written: `size((await query_records({...})).records)`, an `if` test, a `return` value, a `for-of`
|
|
128
132
|
iterable, a tool input. `const x = c ? await t({...}) : null;` is stored as the `if` it means. An
|
|
@@ -192,12 +196,20 @@ A body names a table or document template by its alias (`query_records({ table_i
|
|
|
192
196
|
6. **`option("<field>", "<option>")` names an option where no select is beside it** (a name set once and compared later,
|
|
193
197
|
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 alias. The field is a select or a formula that states `options`.
|
|
194
198
|
The field is looked up among the tables the body reaches; a field or option that does not exist is refused naming both, and
|
|
195
|
-
a field alias that two tables state with different keys for that option is refused naming each table
|
|
196
|
-
|
|
197
|
-
|
|
199
|
+
a field alias that two tables state with different keys for that option is refused naming each table, as is one printed
|
|
200
|
+
(rule 7) where the tables label that option differently. An option
|
|
201
|
+
key written out reads as its alias, but write `option()`: a key is a value no one can read. `options("<field>")` lists
|
|
202
|
+
the field's options in its order, each `{ alias, label }`, found and refused as `option()`'s field is
|
|
203
|
+
(`options("status").map((o) => o.label)`); it is read when the run reads it, so a reorder or a relabel shows at once.
|
|
204
|
+
7. **Text renders labels.** Inside a template, `text(...)` or a text tool input, a select, member or link value renders its display
|
|
198
205
|
text: `` `${record["status"]}` `` writes "Done", not `done`, and `` `${record["status"] ?? ""}` `` writes it too. A
|
|
199
|
-
|
|
200
|
-
|
|
206
|
+
card's action inputs and the option keys its ask offer take the alias, a field's value included. `option("status", "done")`
|
|
207
|
+
and a select input read as `inputs.stage` print a label only in a template, `text(...)` or a document's data: the label
|
|
208
|
+
its field, or the workflow's declared input, states when the run prints it; a multi-select's labels print as a field's
|
|
209
|
+
do. Handed to any other tool input, compared, written or filtered on, each is the option's alias: `title: inputs.stage`
|
|
210
|
+
is the alias, `` title: `Stage ${inputs.stage}` `` prints the label. A name bound to the value (`const s = inputs.stage`,
|
|
211
|
+
`const o = option("status", "done")`, `const v = record.status`) prints the value. A formula stating `options` (a computed category) is read as the single select it is drawn as:
|
|
212
|
+
compared by option, rendered by label.
|
|
201
213
|
|
|
202
214
|
## What an expression reads
|
|
203
215
|
|
|
@@ -359,6 +371,7 @@ The same work can be written with the helpers below, which are additions to Java
|
|
|
359
371
|
`addMonths` (a day past the target month's end lands on its last day), `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,
|
|
360
372
|
`isSameDay`, `isToday`, `isWithinRange`, `datesOn(from, until, days)` (the days from `from` to `until`, both included, falling on weekdays named `mon` to `sun`), `meetsBounds`. A date beside a moment compares by day, so `<=` means
|
|
361
373
|
through that day; `startOfMonth` and `endOfMonth` of a date answer a day
|
|
374
|
+
- **Options**: `option(field, option)` and `options(field)` (see **Fields and options**)
|
|
362
375
|
- **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,
|
|
363
376
|
`randomAlphaNumeric(len)`, `sample(items)` (a random item)
|
|
364
377
|
|
|
@@ -378,8 +391,8 @@ expression — `(x) => <expr>` — or a block of `const` declarations, `if`/`els
|
|
|
378
391
|
ending in `return <expr>;` (`(x) => { … }` or `function (x) { … }`):
|
|
379
392
|
|
|
380
393
|
```js
|
|
381
|
-
const orders = await query_records({ table_id: "orders" });
|
|
382
|
-
const customers = await query_records({ table_id: "customers" });
|
|
394
|
+
const orders = await query_records({ table_id: "orders", all: true });
|
|
395
|
+
const customers = await query_records({ table_id: "customers", all: true });
|
|
383
396
|
const rows = orders.records.map((o) => {
|
|
384
397
|
const c = find(customers.records, (x) => x.id == o.data.customer[0]);
|
|
385
398
|
if (c == null) { return null; }
|
|
@@ -399,8 +412,8 @@ rows once, then read each group by its key. `groupBy` answers an object of lists
|
|
|
399
412
|
is the group a code names, or an empty list:
|
|
400
413
|
|
|
401
414
|
```
|
|
402
|
-
const parties = await query_records({ table_id: "parties" });
|
|
403
|
-
const lines = await query_records({ table_id: "sheet_lines" });
|
|
415
|
+
const parties = await query_records({ table_id: "parties", all: true });
|
|
416
|
+
const lines = await query_records({ table_id: "sheet_lines", all: true });
|
|
404
417
|
const byCode = groupBy(parties.records, (p) => p.data["code"] ?? "");
|
|
405
418
|
const holders = lines.records.map((line) => ({
|
|
406
419
|
line: line.id,
|
|
@@ -60,7 +60,7 @@ A stored text is changed by `edits`, never sent whole again: `set_workflow` (wit
|
|
|
60
60
|
|
|
61
61
|
A long text not stored yet rides a file. `set_workflow` takes `source_file_id` in place of `source`, `set_knowledge` takes `content_file_id` in place of `content`, and `set_template` takes `template_file_id` in place of an html or email `template`: write the text where you work, upload it with `upload_file` (`files`), and pass the `file_id` the upload answers.
|
|
62
62
|
|
|
63
|
-
Many rows come as a file. `query_records` with `as_file: true` sends
|
|
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, `_file.rows` counts its rows, and `all: true` sends the same 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
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`.
|
|
66
66
|
|